Frequently Asked Questions
Common questions and answers about the OpenCart Migration Tool.
Table of contents
- General Questions
- Compatibility Questions
- Requirements Questions
- Migration Process Questions
- Data Migration Questions
- Technical Questions
- Troubleshooting Questions
- After Migration Questions
- Performance Questions
- Licensing Questions
- Support Questions
- Roadmap Questions
- Still Have Questions?
General Questions
What is this tool?
The OpenCart 3 to 4 Migration Tool is an automated solution for migrating your entire OpenCart 3 store to OpenCart 4, including products, customers, orders, and all related data.
Is it free?
Yes! This tool is open-source and released under the MIT License. It’s completely free to use for personal and commercial projects.
Who maintains this tool?
This tool is developed and maintained by Cybernamix AI with contributions from the OpenCart community.
How is this different from manual migration?
| Manual Migration | This Tool |
|---|---|
| Days/weeks of work | Hours |
| Spreadsheet tracking | Automatic ID mapping |
| Manual data entry | Automated batch processing |
| High error rate | Built-in validation |
| No progress tracking | Real-time dashboard |
| Copy/paste images | Automatic transfer |
Compatibility Questions
Which OpenCart versions are supported?
Source (OC3):
- OpenCart 3.0.0.0 to 3.0.3.9
- All 3.x versions supported
Target (OC4):
- OpenCart 4.0.0.0 to 4.0.2.3
- All 4.x versions supported
Can I migrate from OC2 to OC4?
Not directly. First migrate OC2 to OC3 using official OpenCart tools, then use this tool to migrate OC3 to OC4.
Does it work with modified OpenCart?
Yes, but:
- ✅ Custom themes: Supported (universal theme system)
- ✅ Extra products/categories: Supported
- ✅ Custom fields: Supported
- ⚠️ Core file modifications: May need manual handling
- ⚠️ Custom database tables: Won’t migrate automatically
What about my extensions?
The tool includes an extension compatibility checker that:
- Analyzes your OC3 extensions
- Checks OC4 availability
- Recommends alternatives
- Provides marketplace links
Important: Extensions must be reinstalled in OC4. The tool migrates extension data where possible.
Requirements Questions
Do I need OpenCart 4 installed first?
Yes! OpenCart 4 must be freshly installed with default data (languages, currencies, zones). The tool needs this default data for ID mapping.
Can OC3 and OC4 be on the same server?
Yes! You can have both on the same server with different:
- Database names
- Directory paths
- Domain/subdomain names
What server resources do I need?
Minimum:
- PHP 7.4+
- 512MB RAM
- MySQL 5.7+
Recommended:
- PHP 8.0+
- 1GB RAM
- MySQL 8.0+
- SSD storage
Large stores (100K+ products):
- PHP 8.1+
- 2GB RAM
- Dedicated MySQL server
Can I migrate on shared hosting?
Possible but not ideal:
- May hit resource limits
- Slower performance
- Timeouts on large migrations
Recommendation: Use VPS or dedicated server for migration, then move to shared hosting if desired.
Migration Process Questions
How long does migration take?
Depends on store size:
| Store Size | Estimated Time |
|---|---|
| Small (< 5K products) | 30 minutes - 1 hour |
| Medium (5K - 25K) | 1 - 3 hours |
| Large (25K - 100K) | 3 - 8 hours |
| Very Large (> 100K) | 8+ hours |
Note: With bulk processing, very large stores (86K orders) migrate in ~4 minutes instead of 15+ hours.
Can I stop and resume migration?
Yes! The tool tracks progress in SQLite database. You can:
- Stop migration at any time
- Resume from last checkpoint
- Reset and restart if needed
What if migration fails midway?
The tool uses transactions where possible:
- Automatic rollback on errors
- Progress preserved
- Detailed error logs
- Resume capability
Do I need to close my store during migration?
Source (OC3): No, can stay open (read-only recommended) Target (OC4): Yes, keep closed until migration complete
Best practice: Set OC3 to maintenance mode during migration to prevent data changes.
Will customer passwords be migrated?
No. OC3 uses SHA1, OC4 uses bcrypt. Customers must reset passwords after migration.
Options:
- Send password reset emails to all customers
- Force password reset on first login
- Use “forgot password” feature
Data Migration Questions
What data gets migrated?
✅ Migrated automatically:
- Categories (with images)
- Products (with images, options, variants)
- Customers (password reset required)
- Orders (complete history)
- Manufacturers
- Attributes
- Filters
- Admin users
- Reviews
- Information pages
- Banners
- Downloads
- Vouchers
⚠️ Requires manual configuration:
- Store settings (selective)
- Tax settings
- Payment methods
- Shipping methods
- Extensions
- Themes
❌ Not migrated:
- Extension code/files
- Theme template files
- Customer passwords (must reset)
- Custom database tables
Are product images migrated?
Yes! The tool automatically:
- Copies images from OC3 to OC4
- Maintains directory structure
- Validates successful transfer
- Reports missing images
Path configuration required:
'images' => [
'source_path' => '/path/to/oc3/image',
'target_path' => '/path/to/oc4/image',
]
What happens to product SEO URLs?
SEO URLs are migrated! The tool:
- Transfers all URL aliases
- Maintains SEO structure
- Preserves language-specific URLs
- Updates internal links
Are multi-language stores supported?
Yes! The tool migrates:
- All languages
- Language-specific content
- Multi-language SEO URLs
- Language-specific descriptions
What about multi-store?
Current: Single store migration Planned (V2): Multi-store support with:
- Store detection
- Store mapping
- Store consolidation options
Technical Questions
Does it require programming knowledge?
No! The web interface is user-friendly:
- Point-and-click navigation
- Visual progress tracking
- Guided workflow
- Detailed instructions
Technical skills helpful for:
- Troubleshooting issues
- Custom modifications
- Advanced configurations
Can I run it from command line?
Current: Web-based only Planned (V2): CLI interface for:
- Automated migrations
- Cron scheduling
- Server automation
How does ID mapping work?
The tool creates mapping tables that link OC3 IDs to OC4 IDs:
OC3 Category ID: 5 → OC4 Category ID: 12
OC3 Product ID: 100 → OC4 Product ID: 205
This ensures all relationships (product→category, order→customer) remain intact.
Can I customize the migration?
Yes! Several ways:
- Configuration: Adjust batch sizes, timeouts
- Selective migration: Choose what to migrate
- Custom transformations: Add in table dictionaries
- Hooks: Use hook system for custom logic
- Extensions: Create custom migration steps
Is my data secure?
Yes:
- Local processing: All data stays on your server
- No external calls: No data sent to third parties
- Encrypted connections: Use HTTPS for web interface
- Database security: Use dedicated DB users with minimal permissions
Troubleshooting Questions
Migration failed, what do I do?
- Check error logs:
logs/migration.log - Identify the error: Look for error messages
- Fix the issue: See Troubleshooting Guide
- Reset and retry: Use dashboard reset button
Out of memory errors?
Solutions:
// Increase memory limit
'memory_limit' => '1G',
// Reduce batch size
'default_batch_size' => 500,
Timeouts during migration?
Solutions:
// Increase timeout
'time_limit' => 7200, // 2 hours
# Apache
Timeout 7200
# Nginx
proxy_read_timeout 7200s;
Record counts don’t match?
Common causes:
- Filtered records (deleted, inactive)
- Duplicates in OC3
- Validation failures
Check logs for skip reasons and validation errors.
Images not displaying?
Verify:
- Image paths are correct
- Files were copied successfully
- Permissions are correct (755 for directories, 644 for files)
- Check OC4 error logs
After Migration Questions
Do I need to keep the migration tool?
After successful migration and validation:
- ✅ Keep for records/logs
- ✅ Keep if you might need to re-migrate
- ❌ Can remove if you’re confident
Can I migrate again if something’s wrong?
Yes! You can:
- Restore OC4 from backup
- Fix the issue
- Reset migration tool
- Re-run migration
How do I validate the migration?
The tool includes built-in validation:
- Data integrity checks
- Record count verification
- Foreign key validation
- Image verification
Manual checks:
- Browse products on frontend
- Test checkout process
- Check admin functionality
- Verify images display correctly
- Test extensions
What about my old OC3 store?
Best practice:
- Keep OC3 running temporarily
- Monitor OC4 for issues
- Once confident, redirect OC3 to OC4
- Keep OC3 backup for 30+ days
- Eventually decommission OC3
Performance Questions
Why is migration slow?
Possible causes:
- Large batch sizes
- Limited RAM
- Remote databases
- Slow disk I/O
- Image validation enabled
Solutions:
- Reduce batch size
- Increase memory limit
- Use local databases
- Use SSD storage
- Disable validation during migration
Can I speed up migration?
Yes! Several optimizations:
'migration' => [
'default_batch_size' => 2000, // Increase if you have RAM
'memory_limit' => '2G', // More memory
],
'images' => [
'validation' => false, // Validate after migration
]
Also:
- Use local databases (not remote)
- Run on dedicated server
- Use PHP 8+
- Enable OPcache
Licensing Questions
Is it really free?
Yes! MIT License means:
- ✅ Free for commercial use
- ✅ Free to modify
- ✅ Free to distribute
- ✅ Free forever
Can I use it for client projects?
Absolutely! Use it to migrate client stores and even charge for your migration services.
Can I resell it?
You can offer migration services using this tool, but you cannot:
- ❌ Sell the tool itself as your own
- ❌ Remove copyright notices
- ❌ Claim you created it
Support Questions
Where can I get help?
- Documentation: Start here - most questions are answered
- Troubleshooting Guide: Common issues and solutions
- GitHub Issues: Report bugs
- GitHub Discussions: Ask questions
- Community: OpenCart forums
Is there paid support?
Current: Community support only (free) Future: May offer premium support for enterprise customers
Can you migrate my store for me?
This tool enables you to migrate yourself. For professional migration services, contact Cybernamix AI or hire OpenCart developers.
Roadmap Questions
What’s coming in V2?
Planned features:
- CLI migration interface
- Configuration export/import
- Multi-store support
- Remote migration capability
- Advanced theme transformers
- Custom code migration
- Rollback functionality
- Scheduled migrations
When will V2 be released?
No specific date yet. Follow the GitHub repository for updates.
Can I request features?
Yes! Create a feature request on GitHub.
Still Have Questions?
Didn’t find your answer?
- Check Documentation
- Read Troubleshooting Guide
- Search GitHub Issues
- Ask on GitHub Discussions
Found a bug?
- Report on GitHub Issues
- Include all relevant details
- Provide error logs
Want to contribute?
- Read Contributing Guide
- Check open issues
- Submit pull requests