Troubleshooting Guide

Common issues and solutions for the OpenCart Migration Tool.

Table of contents

1. Installation Issues
   1. Database Connection Failed
   2. Permission Denied Errors
   3. PHP Extension Missing
2. Migration Issues
   1. Default Data Migration Fails
      1. 1. OC4 Not Properly Installed
      2. 2. Table Prefix Mismatch
      3. 3. Missing Default Tables
   2. Out of Memory Errors
   3. Migration Hangs/Freezes
   4. Image Transfer Fails
   5. Foreign Key Constraint Errors
3. Performance Issues
   1. Slow Migration Speed
   2. High Memory Usage
4. Data Issues
   1. Record Count Mismatch
      1. 1. Filtered Migration
      2. 2. Duplicate Records
      3. 3. Data Validation Failures
   2. Broken Relationships
5. Extension Issues
   1. Extensions Not Working After Migration
6. Common Error Messages
   1. “Call to undefined method”
   2. “Maximum execution time exceeded”
   3. “Headers already sent”
7. Getting Additional Help
   1. Before Requesting Help
   2. Where to Get Help
   3. Reporting Bugs
8. Emergency Recovery
   1. Migration Corrupted OC4 Database
   2. Lost Progress
9. Preventive Measures
   1. Before Starting Migration
   2. During Migration
   3. After Migration
10. Still Having Issues?

---

Installation Issues

Database Connection Failed

Symptoms:

• “Could not connect to database” error
• Installation fails at database check

Solutions:

# 1. Test MySQL connection manually
mysql -u username -p -h localhost database_name

# 2. Check credentials in config/config.php
'database' => [
    'source' => [
        'host' => 'localhost',  # Try '127.0.0.1' if localhost fails
        'database' => 'correct_db_name',
        'username' => 'correct_username',
        'password' => 'correct_password',
    ]
]

# 3. Verify MySQL is running
sudo systemctl status mysql

# 4. Check MySQL bind address
# In /etc/mysql/mysql.conf.d/mysqld.cnf
bind-address = 127.0.0.1  # Should allow localhost connections

Permission Denied Errors

Symptoms:

• Cannot write to storage/ or logs/
• “Permission denied” in error logs

Solutions:

# Linux/Unix
sudo chown -R www-data:www-data /path/to/migration-tool
sudo chmod -R 755 storage/ logs/
sudo chmod 666 config/config.php

# Windows (PowerShell as Administrator)
icacls "C:\path\to\migration-tool\storage" /grant Users:F /T
icacls "C:\path\to\migration-tool\logs" /grant Users:F /T

PHP Extension Missing

Symptoms:

• “Extension not loaded” error
• Installation checker shows missing extensions

Solutions:

# Check installed extensions
php -m

# Ubuntu/Debian
sudo apt-get install php7.4-mysql php7.4-sqlite3 php7.4-gd php7.4-mbstring

# CentOS/RHEL
sudo yum install php74-mysql php74-pdo php74-gd php74-mbstring

# macOS (Homebrew)
brew install php@7.4
brew install php-mysql php-sqlite3

# Restart web server
sudo systemctl restart apache2
# or
sudo systemctl restart php7.4-fpm

---

Migration Issues

Default Data Migration Fails

Symptoms:

• Migration fails at first step
• “ID mapping failed” error

Common Causes & Solutions:

1. OC4 Not Properly Installed

OpenCart 4 must be freshly installed with default data (languages, currencies, zones).

Solution:

# Verify OC4 has default data
mysql -u root -p opencart4_db -e "SELECT COUNT(*) FROM oc_language;"
# Should return > 0

# If empty, reinstall OpenCart 4 completely

2. Table Prefix Mismatch

Solution:

// Check config/config.php
'database' => [
    'source' => [
        'table_prefix' => 'oc_'  // Must match actual prefix
    ],
    'target' => [
        'table_prefix' => 'oc_'  // Must match actual prefix
    ]
]

// Verify actual prefix
mysql -u root -p -e "SHOW TABLES FROM opencart3_db;"

3. Missing Default Tables

Solution:

-- Verify required tables exist
USE opencart4_db;
SHOW TABLES LIKE '%language%';
SHOW TABLES LIKE '%currency%';
SHOW TABLES LIKE '%zone%';

-- If tables missing, reinstall OC4

Out of Memory Errors

Symptoms:

• “Allowed memory size exhausted” error
• Migration stops mid-process

Solutions:

// 1. Increase memory in config/config.php
'migration' => [
    'memory_limit' => '1G',  // Increase from 512M
]

// 2. Reduce batch size
'migration' => [
    'default_batch_size' => 500,  // Reduce from 1000
]

# 3. Increase PHP memory limit globally
# Edit php.ini
memory_limit = 1G

# Restart web server
sudo systemctl restart apache2

Migration Hangs/Freezes

Symptoms:

• Progress bar stops moving
• No error messages
• Browser shows “Loading…”

Solutions:

// 1. Increase PHP timeout
'migration' => [
    'time_limit' => 7200,  // 2 hours instead of 1
]

# 2. Check Apache/Nginx timeout settings
# Apache: /etc/apache2/apache2.conf
Timeout 7200

# Nginx: /etc/nginx/nginx.conf
proxy_read_timeout 7200s;
fastcgi_read_timeout 7200s;

# 3. Check PHP max_execution_time
# php.ini
max_execution_time = 7200

# 4. Monitor progress in logs
tail -f logs/migration.log

Image Transfer Fails

Symptoms:

• Images not copying
• “Image not found” errors
• Broken images in OC4

Solutions:

// 1. Verify paths in config/config.php
'images' => [
    'source_path' => '/absolute/path/to/opencart3/image',
    'target_path' => '/absolute/path/to/opencart4/image',
]

// 2. Check paths are absolute, not relative
// ❌ Wrong: 'source_path' => '../opencart3/image'
// ✅ Correct: 'source_path' => '/var/www/opencart3/image'

# 3. Verify permissions
ls -la /path/to/opencart3/image
ls -la /path/to/opencart4/image

# Should be readable/writable by web server user
sudo chown -R www-data:www-data /path/to/opencart4/image
sudo chmod -R 755 /path/to/opencart4/image

# 4. Check disk space
df -h

Foreign Key Constraint Errors

Symptoms:

• “Cannot add or update a child row” error
• Migration fails midway through step

Solutions:

# 1. Ensure Default Data migration completed first
# Check logs for: "Default Data migration: COMPLETED"

# 2. Verify ID mappings exist
mysql -u root -p migration_tracking -e "SELECT * FROM id_mappings LIMIT 10;"

# 3. Check for orphaned records in source
# Example: Products with invalid category_id
mysql -u root -p opencart3_db -e "
SELECT p.product_id FROM oc_product p
LEFT JOIN oc_category c ON p.category_id = c.category_id
WHERE p.category_id > 0 AND c.category_id IS NULL;"

# 4. Reset and restart migration
# Use reset feature in dashboard

---

Performance Issues

Slow Migration Speed

Symptoms:

• Migration takes hours for moderate datasets
• Progress bar moves very slowly

Solutions:

// 1. Enable bulk processing
'migration' => [
    'default_batch_size' => 2000,  // Increase if you have memory
    'memory_limit' => '1G',
]

// 2. Disable image validation during migration
'images' => [
    'validation' => false,  // Validate after migration instead
]

-- 3. Optimize database
OPTIMIZE TABLE oc_product;
OPTIMIZE TABLE oc_order;
ANALYZE TABLE oc_product;
ANALYZE TABLE oc_order;

-- 4. Add indexes if missing
SHOW INDEX FROM oc_product;

# 5. Use local databases (not remote)
# Remote DB connections are significantly slower

# 6. Close unnecessary applications
# Free up system resources

High Memory Usage

Solutions:

// Aggressive memory management
ini_set('memory_limit', '512M');  // Set reasonable limit
gc_enable();  // Enable garbage collection

// Process in smaller batches
'migration' => [
    'default_batch_size' => 100,  // Smaller batches
]

---

Data Issues

Record Count Mismatch

Symptoms:

• Validation shows source count ≠ target count
• “Record counts do not match” error

Causes & Solutions:

1. Filtered Migration

Some records may be intentionally skipped (e.g., deleted products, inactive customers)

Solution: Check migration logs for skip reasons

2. Duplicate Records

OC3 may have duplicates that OC4 rejects

Solution:

-- Find duplicates in OC3
SELECT email, COUNT(*) FROM oc_customer
GROUP BY email HAVING COUNT(*) > 1;

-- Clean duplicates before migration

3. Data Validation Failures

Records failing OC4’s stricter validation

Solution: Check logs for validation errors and fix source data

Broken Relationships

Symptoms:

• Products missing categories
• Orders missing customer data
• Images not displaying

Solutions:

-- 1. Verify ID mappings
SELECT * FROM id_mappings WHERE old_table = 'category';

-- 2. Check for orphaned records
SELECT * FROM oc_product p
LEFT JOIN oc_category c ON p.category_id = c.category_id
WHERE c.category_id IS NULL AND p.category_id > 0;

-- 3. Re-run affected migration steps
-- Use dashboard to reset and re-migrate specific steps

---

Extension Issues

Extensions Not Working After Migration

Symptoms:

• Extension installed but not functioning
• Settings missing
• Errors in OC4 error logs

Solutions:

1. Check OC4 Compatibility

   Extension may not be compatible with OC4
   Look for OC4 version on OpenCart marketplace
   

2. Reinstall Extensions

   Many extensions need fresh installation in OC4
   Download OC4 version
   Install manually
   Configure settings
   

3. Check Extension Analysis

   Use Extensions Management step
   Review compatibility report
   Follow recommendations
   

---

Common Error Messages

“Call to undefined method”

Cause: Missing class or method

Solution:

# Check autoloader
# Verify class file exists in src/
ls -la src/Services/
ls -la src/Controllers/

# Check for typos in class names
# Restart web server
sudo systemctl restart apache2

“Maximum execution time exceeded”

Solution:

// Increase timeout
set_time_limit(3600);  // 1 hour

// Or in php.ini
max_execution_time = 3600

“Headers already sent”

Cause: Output before headers

Solution:

// Check for whitespace or echo before headers
// Verify no BOM in PHP files

// Find the file
// Error message shows: "output started at file.php:10"
// Remove echo/print/whitespace at that location

---

Getting Additional Help

Before Requesting Help

1. Check logs

   tail -n 100 logs/migration.log
   

2. Note versions
   • OpenCart 3 version
   • OpenCart 4 version
   • PHP version
   • Tool version
3. Collect error messages
   • Full error text
   • Stack trace if available
   • Steps to reproduce

Where to Get Help

• Documentation: https://kunwar-shah.github.io/opencart-migration-tool
• GitHub Issues: Report bugs
• Discussions: Ask questions

Reporting Bugs

Include in bug report:

• Environment details
• Steps to reproduce
• Expected vs actual behavior
• Error logs
• Database sizes

---

Emergency Recovery

Migration Corrupted OC4 Database

Solution:

# 1. Stop migration immediately

# 2. Restore OC4 from backup
mysql -u root -p opencart4_db < oc4_backup.sql

# 3. Fix the issue causing corruption

# 4. Restart migration from beginning

Lost Progress

Solution:

# Progress is stored in SQLite database
# Check: storage/migration_tracking.sqlite

# If database corrupted:
# 1. Restore OC4 from backup
# 2. Delete tracking database
rm storage/migration_tracking.sqlite

# 3. Restart migration

---

Preventive Measures

Before Starting Migration

• Backup both databases
• Test on staging environment first
• Verify all requirements met
• Check disk space sufficient
• Plan maintenance window
• Document current configuration

During Migration

• Monitor logs in real-time
• Keep browser tab active
• Don’t interrupt process
• Note any warnings

After Migration

• Run validation checks
• Test critical functionality
• Verify data integrity
• Check image display
• Test orders and checkout

---

Still Having Issues?

If none of these solutions work:

1. Enable debug mode:

   // config/config.php
   'app' => [
    'debug' => true,
   ]
   

2. Check detailed error logs

3. Create GitHub issue with full details

4. Community may have encountered similar issues