Bob's Guides

MODX Upgrade FAQ

Upgrade Steps

Here are the steps I use to upgrade Bob's Guides. The site is down for about 10 minutes at the most. The last time I did it, the whole process took about 10 minutes (not counting backing up the site), and the site was down for less than 3 minutes.

1. Clear the site cache and the two logs (under the Reports menu)
2. Log out!!! This is very important
3. Back up your site!:
1. In PhpMyAdmin, select your MODX database and export it to an SQL file on your local machine
2. It's not a bad idea to take open the SQL file in a text editor to make sure all the tables are there
3. In cPanel'sFile Manager, go to your root directory, select all files and directories, and compress them to a .zip archive
4. Download the .zip archive to your local machine
5. It's not a bad idea to explore the .zip archive on your local machine and make sure all the directories are there
4. Download the current stable version of MODX Revolution from modx.com/downloads
5. Extract all files in the archive to a directory on your local machine
6. Go into that directory — you should see the assets, core, manager, and setup directories
7. Select all files and directories and create a new archive using your own unique name (e.g., MyMODX2.1.3.zip)
8. In cPanel's File Manager at the remote site, delete all files in the core/cache directory
9. From the core/cache directory, go up two levels to the MODX root directory — you should see the assets, core, and manager directories
10. Upload the .zip file you created from your local machine (e.g., MyMODX2.1.3.zip)
11. Rename index.php to index.php.bak, the site will be down from this point on
12. Extract the files in the .zip file to the MODX root directory
13. Look at the core directory to confirm that it was modified today (you may have to go up a level and back down to refresh it)
14. Open a new browser window and clear the cache (especially the java cache) and cookies
15. Go to https://yoursite.com/setup
16. Follow the prompts (make sure that the Upgrade Install checkbox is checked — if not, don't proceed!)
17. Let the install delete the setup directory — if you need to reinstall, you can re-upload just that directory
18. Once Setup is finished, the site should be back up and using the new version

Troubleshooting

If you tried to upgrade from MODX 1.x to MODX 2.x, at present there's no simple upgrade method. Simply installing the files and running upgrade will result in a complete disaster.

If you did an upgrade of MODX Revolution from an earlier version of MODX Revolution, here are some things to try if you run into trouble:

• Try running an upgrade install of MODX (again, if necessary) and then clearing your browser cache and cookies (especially the java cache) before logging in.
• Try logging in from another browser.
• Check the information in the core/config/config.inc.php file in case you overwrote it with one from your local site (pay special attention to the server name, DB name, and password, the character set, and the location of the processors directory).
• Try deleting the contents of the core/cache directory manually.
• If the Manager works, but not the front end. Try turning off Friendly URLs (use_friendl_urls System Setting), visit the site, then turn them back on again. That will refresh the uri field of all resources.
• Check the paths in the four config.core.php files (they should all point to the directory containing the /core directory):
  • MODX root directory
  • /manager/
  • /connectors/
  • /setup/includes/
• In the modx_system_settings table in the database, set the compress_css and compress_js settings to 0. Set the manager_theme setting to default.
• In the modx_site_plugins table, set the 'disabled' field of all plugins to 1. Once the site is working normally, re-enable the plugins one by one until something breaks.
• Check the path in the modx_workspaces table in the database
• If you are getting PHP errors, you may have extras with deprecated functions that were removed in the current version. The error message will usually indicate the problem element by ID number. You can disable plugins on the Create/Edit Plugin panel. You can disable snippets by putting a space between the two opening brackets.
• In upgrading from certain versions, it may be necessary to delete and remove the entire TinyMCE package, download it again, and reinstall it.
• There are three System Settings that should be missing or empty in the modx_system_settings table in the database:
  • session_name
  • session_cookie_path
  • session_cookie_domain
  Once you've altered them in PhpMyAdmin, delete the core/cache/config.cache.php file, clear your browser cache and cookies, and login again.

Here are some more possibilities:

• File permissions or your FTP program may have prevented some new files from overwriting the old ones.
• The upgrade process may have changed some file or folder permissions so that MODX can't read or write necessary files
• One or more files got corrupted during the download from MODX, or the upload to the site. Try the whole process again.
• The new version may contain code that violates the mod_security rules at your host (for example, mod_security causes trouble downloading packages after an upgrade to MODX 2.3 on some hosts).

If none of that works, you may have a missing or corrupted file in your install -- it happen. Try uploading the files again using the method described above. Also, see the MODX Installation FAQ for more ideas.

Disaster Recovery

If everything fails and you want to revert to your backup of the earlier version, follow these steps. Important: this assumes that you followed the backup steps above correctly.

1. If you were able to log into the Manager, log out
2. In the cPanel File Manager, rename index.php to index.php.bak
3. In PhpMyAdmin, select your MODX database and drop all tables in the database (don't drop the database itself!)
4. Still in PhpMyAdmin in the same database, import the SQL file you saved earlier
5. In cPanel's File Manager, go to the MODX root directory
6. Delete the core, manager, and connectors directories, and the setup directory if it's still there
7. Upload the .zip file you saved earlier
8. Extract all the files to the root directory
9. Delete the index.php.bak file
10. The site should now be back up with the old version
11. It shouldn't be necessary, but if you run into trouble, you can always upload the setup directory from the previous version and run setup again

Copyright © 2011-2025
Bob Ray