If a migration fails or produces unexpected results, use this page to identify the cause and fix it. Also check the agent log (/opt/opterius-agent/logs/agent.log) and the Laravel log (/opt/opterius/storage/logs/laravel.log) for detailed error output.
Symptom table
| Symptom | Likely cause | Fix |
|---|---|---|
| "File not found" when parsing the backup | The archive path does not exist on the Opterius server | Transfer the backup to the server first — see Step 2 of Migration Step by Step. Double-check the path you entered in the panel. |
| Migration stuck at a percentage for more than 10 minutes | Queue worker is not running | systemctl restart opterius-queue — see below. |
| Database import fails for a large database | Import timeout | Import the dump manually — see below. |
| Email not working after migration | MX records still point to old server | Update MX records in the DNS zone — see below. |
| Domain not loading after migration and DNS cutover | DNS not yet propagated, or TTL too high | Test with /etc/hosts override; wait for TTL expiry — see Verifying Migration. |
| WordPress shows database connection error | DB password was regenerated and wp-config.php has the old password | Update DB_PASSWORD in wp-config.php — see below. |
| "Permission denied" errors on site pages | File ownership not reset correctly after import | Fix with chown — see below. |
| Cron jobs missing or paths broken | Username changed during migration; path rewrite missed an edge case | Re-add cron jobs manually — see below. |
| SSL shows as expired or invalid | Cert was expired at time of import and was skipped | Issue a new Let's Encrypt cert in Server Mode → Accounts → [account] → SSL. |
Migration stuck — queue worker not running
Check the worker:
systemctl status opterius-queue
If it shows inactive or failed, restart it:
systemctl restart opterius-queue
Watch it come up:
journalctl -u opterius-queue -f
If the migration job was already queued, it will resume processing within a few seconds of the worker starting. If the job shows as failed in the panel rather than pending, re-submit it from Server Mode → Migrations.
Database import fails for a large database
The agent's /backup/restore call can time out on databases larger than a few hundred MB. Import the database dump manually instead:
-
Extract the database dump from the pkgacct archive:
cd /tmp tar -xzf /var/backups/cpmove-username.tar.gz --wildcards 'mysql/*' -
Find the dump file:
ls /tmp/mysql/ -
Create the database and user in Opterius Panel first (Server Mode → Accounts → [account] → Databases → Add Database).
-
Import the dump directly:
mysql -u root -p database_name < /tmp/mysql/database_name.sql -
Verify the import completed and the row counts look correct.
Email not working after migration
Check 1: MX records
dig MX domain.com +short
If MX records still point to the old cPanel server's hostname, email will be delivered there, not to Opterius. Update the MX record in the DNS zone:
Server Mode → DNS → Zones → domain.com → Edit → find the MX record → update it to the Opterius server's hostname.
Check 2: Dovecot is running
systemctl status dovecot
Check 3: Mail is not being blocked by the firewall
# UFW
ufw status | grep -E '25|465|587|993|995'
# firewalld
firewall-cmd --list-ports
Ports 25, 465, 587, 993, and 995 must be open.
WordPress shows database connection error
Database passwords are regenerated during migration. The new credentials are shown in:
Server Mode → Accounts → [account] → Databases → [database name]
Update wp-config.php:
nano /home/username/domain.com/public_html/wp-config.php
Find and update:
define( 'DB_PASSWORD', 'new_password_here' );
Save and reload the site.
File ownership incorrect
If the agent did not correctly reset file ownership after import:
chown -R username:username /home/username/
# Restore correct ACL for Nginx traverse access
setfacl -m u:www-data:x /home/username
setfacl -m u:www-data:x /home/username/domain.com
Standard file permissions:
find /home/username/domain.com/public_html -type f -exec chmod 644 {} \;
find /home/username/domain.com/public_html -type d -exec chmod 755 {} \;
Cron jobs missing or broken paths
Check what was imported:
crontab -l -u username
If entries are missing or paths are wrong, add them manually:
crontab -e -u username
Common path to fix: cPanel uses /home/username/public_html/, Opterius uses /home/username/domain.com/public_html/. Update any hardcoded paths in the cron commands.
Still stuck?
Check both log files for detailed error messages:
tail -n 200 /opt/opterius-agent/logs/agent.log
tail -n 200 /opt/opterius/storage/logs/laravel.log
The agent logs include the exact command that failed, the exit code, and any stderr output. This is usually enough to pinpoint the cause.