THE COMPLETE SUITECRM MIGRATION & ERROR FIX TUTORIAL

1. Introduction

Migrating SuiteCRM from one server to another is not as straightforward as copying files and importing the database. SuiteCRM contains a mixture of Laravel/Symfony (SuiteCRM 8) and the older SuiteCRM 7 legacy system.
When moving to a new server, several parts break:

• Internal paths stored in configuration files
• Cache generated for the old environment
• File permissions
• Symfony cache
• Legacy cache
• Composer dependencies
• Missing PHP extensions
• Apache rewrite issues

If even one of these is incorrect, your CRM will load an empty page or return HTTP 500 error.

This tutorial explains every step, every command, every file, and how to fix the error from scratch.

---

2. Why You Get HTTP 500 After Migration

During migration, SuiteCRM breaks because:

1. Cached files still point to the old server directory.
2. config.php contains old paths.
3. .env.local contains old domain and folder location.
4. Permissions (especially on XAMPP servers) get reset.
5. Symfony cache is corrupted.
6. Legacy SuiteCRM 7 cache is corrupted.
7. PHP modules required by SuiteCRM are missing on the new server.
8. Composer autoload cannot rebuild the cache.

When these collide, you get:

• “This page isn’t working”
• “HTTP ERROR 500”
• Cache:clear returned with error code 255

The good news is: all issues can be fixed with a proper checklist.

---

3. Migration Checklist (What MUST be done after moving SuiteCRM)

When you migrate SuiteCRM, follow this exact order:

Step 1 — Copy SuiteCRM files

Step 2 — Import MySQL database

Step 3 — Fix ownership and permissions

Step 4 — Clear SuiteCRM legacy cache

Step 5 — Clear Symfony cache

Step 6 — Update config.php

Step 7 — Update .env.local

Step 8 — Install required PHP extensions

Step 9 — Restart Apache

Step 10 — Verify logs

If any one of these steps is skipped, your CRM will break.

---

4. Fixing Permissions (MOST IMPORTANT PART)

SuiteCRM is very sensitive to permissions.
On Linux with XAMPP, SuiteCRM typically uses the user daemon.

Run these commands:

cd /opt/lampp/htdocs/myhospitalnow/suitecrm

sudo chown -R daemon:daemon .
sudo find . -type d -exec chmod 755 {} \;
sudo find . -type f -exec chmod 644 {} \;

sudo chmod -R 775 var
sudo chmod -R 775 public/legacy/cache
sudo chmod -R 775 public/legacy/upload
sudo chmod -R 775 public/legacy/custom

This ensures SuiteCRM can write cache and session files.

---

5. Clearing SuiteCRM Caches

SuiteCRM maintains two separate cache systems.

5.1 — Clear Symfony cache

rm -rf var/cache/*

5.2 — Clear SuiteCRM legacy cache

rm -rf public/legacy/cache/*

If these are not cleared, the system will try to load old server paths and crash.

---

6. Correcting the SuiteCRM Legacy config.php

This file lives in:

public/legacy/config.php

You must update three things.

6.1 — Correct site URL

'site_url' => 'https://myhospitalnow.com/crm',

6.2 — Correct host name

'host_name' => 'myhospitalnow.com',

6.3 — Correct SuiteCRM path

'suitecrm_dir' => '/opt/lampp/htdocs/myhospitalnow/suitecrm/public/legacy',

If the old server directory is found here, the CRM immediately fails with HTTP 500.

---

7. Correcting SuiteCRM 8 .env.local

The Symfony environment file is located at:

.env.local

You must update:

SUITECRM_URL="https://myhospitalnow.com/crm"
LEGACY_DIR="/opt/lampp/htdocs/myhospitalnow/suitecrm/public/legacy"
APP_ENV=prod
APP_DEBUG=0

If LEGACY_DIR contains the old server path, composer and Symfony cache clearing will fail.

---

8. Fix Composer Issues

When you ran:

composer install

You received:

Script cache:clear returned with error code 255

This happens because:

• Cache directory is not writable
• .env.local contains old paths
• Symfony cannot rebuild cache

After fixing permissions and .env.local, run:

php bin/console cache:clear --no-warmup --env=prod
php bin/console cache:warmup --env=prod

If this works without error, composer issues are fixed.

---

9. Ensure All PHP Extensions Are Installed

SuiteCRM needs these PHP modules:

• php-intl
• php-zip
• php-xml
• php-mbstring
• php-gd
• php-curl
• php-mysql

Check installed modules:

php -m

If missing, install them.

---

10. Fix Apache Rewrite for SuiteCRM

SuiteCRM requires mod_rewrite.

Enable:

sudo a2enmod rewrite
sudo systemctl restart apache2

Ensure .htaccess exists with:

RewriteEngine On
RewriteBase /crm/

---

11. Checking Logs to Identify Hidden Errors

SuiteCRM errors are stored in three places.

11.1 — Apache error logs

For XAMPP:

tail -n 50 /opt/lampp/logs/error_log

11.2 — SuiteCRM legacy logs

tail -n 50 public/legacy/suitecrm.log

11.3 — Symfony logs

tail -n 50 var/log/prod.log

These logs will show the exact reason for 500.

---

12. Common Issues During Composer Operations

When running composer, you might see:

• “Do not run composer as root”
• PSR-4 autoload warnings
• Abandoned package warnings
• Cache:clear failure

These messages do NOT cause a 500 error.
The real cause is always wrong paths + wrong permissions.

Composer simply re-reads autoload files, and when paths don’t match the new server, it fails clearing cache.

---

13. Final Verification Checklist

After migration, ensure these are correct:

1. config.php

Correct site URL, host name, and suitecrm path.

2. .env.local

Correct SuiteCRM URL and legacy directory.

3. Permissions

All write folders are writable.

4. Cache

Legacy + Symfony cache cleared.

5. Composer

Cache cleared without errors.

6. PHP Modules

All required extensions installed.

7. Apache

Rewrite working.

If all seven items are correct, SuiteCRM will run successfully.

---

14. Conclusion

Migrating SuiteCRM is not difficult, but it requires understanding how both the old legacy engine and the new Symfony-based SuiteCRM 8 interact.
The most common cause of HTTP 500 errors is a combination of:

• Wrong file paths
• Wrong permissions
• Unclean cache
• Missing PHP modules
• Invalid composer cache

Just tell me.