General MODX Weirdness Page

Sometimes, even the most carefully constructed site can go south on you. Here is some general advice on how to troubleshoot MODX weirdness. There is more information about specific issues here. All of the sections below contain information that might help you, but look first in the one that applies to your situation.

If you don't find an answer here, ask for help in the appropriate section of the MODX Forums. If they might have a bearing on your problem, be sure to include your browser version, MODX version, hosting service, Apache version, PHP version, and MySQL version.

A Word about Re-running the Install

For many MODX users, re-running Setup (for MODX Revolution) or Install (for MODX Evolution) is a scary proposition, especially if you've done a lot of work on a site. The fact is, though, that MODX will never touch your content during installation. It may update the MODX core, manager, and connectors directories and set some paths, but it won't delete any files or touch anything else. It won't change any Resources, Permissions, Policies, Form-customization rules, System Settings, Lexicon entries, or any Elements that you've created (Categories, Templates, Template Variables, Chunks, Snippets, Plugins, or Property Sets). It also won't touch files in any other directories. I've run upgrade installs on live sites literally hundreds of times and never had a problem. The bottom line is that it can't hurt and it might help.

Weirdness on a Fresh Install

If there are errors during the install, you'll usually see an error message telling you what's wrong. If the install goes smoothly, you many still see an error when you try to use MODX. In either case, Search Google (or your favorite search engine) for the error message along with the keywords MODX and either Evolution or Revolution. You'll almost certainly find information about what to do. If not, post a question in the MODX Forums.

If the install goes smoothly but MODX is still not working and you see no error message, diagnosing the problem is a little more challenging. One possible culprit is file and directory permissions and/or ownership. These need to be set correctly and the correct settings depend on your host. There's some good information here on settings (and some other possible issues).

Everett Griffiths has written an excellent diagnostic script that you can find here.

Sometimes, you can get a clue from the MODX error log. For MODX Revolution, you can see it under the Reports menu or on the disk at core/cache/logs/error.log. You can look at the file with any text editor. If there is nothing in the error log, you can sometimes find useful information in the Apache error log using your host's cPanel (or the equivalent).

Another possibility is that one or more files was missed or corrupted in the transfer. If you used FTP to move all the files individually, this problem is more common than you might think. FTP is simply not very reliable when transferring that many files. See the information here. The page is about upgrading, but the section on transferring the MODX files is relevant to new installs.

If none of the solutions above works, there are some other things you can check. If you see a message about calling get() on a non-object or there's an indication that MODX isn't finding something, it usually points to a path issue. The first thing to check is the MODX configuration file. For Revolution, it's core/config/ For Evolution, it's manager/includes/ Check all the paths and URLs in the file very carefully and make sure each one points to the right place. In Revolution, the connectors path is a common culprit. Another place to check for path issues is in the database. Using PhpMyAdmin, check the path in the modx_workspaces table.

If you can't log in to the Manager or if the Manager looks wrong (e.g., no menus, missing or empty Resource tree, blank panels, etc.), try changing the compress_js and compress_css System Settings. If you can access the Manager go to System | System Settings and type compress in the search box at the upper right. If you can't access the Manager, use PhpMyAdmin and make the changes in the modx_system_settings table. Find the two settings and change the value from 1 to 0, then click on the "Go" button.

If you've tried changing the "compress" settings, but some parts of the Manager are missing, another thing to try is to do a "View Source" on a Manager page that doesn't look right. There are lines that include CSS and JS files, which should show as links in the source. If you click on each one, you should see the code it's loading (or your browser asking you what to do). If you don't, or you get a "File not found" error, it means that the path to that file is wrong (see the note above about checking the paths in Another, somewhat rare, possibility that can cause blank sections in the Manager has to do with the ht.access</fixedpre or <fixedpre>.htaccess file in the manager directory. Typically, the file is named ht.access and usually this is correct (that file will be ignored). Try renaming that file to the other alternative and deleting all the files in the core/cache directory before logging in. If it doesn't help, be sure to change the name back to what it was and delete the files again.

If you are unable to save Resources or Elements (e.g. Chunks and Snippets), the two most likely causes are mod_security and a date/timezone problem. In order for MODX to save objects reliably and reset a Resource's Template in recent versions of PHP, the PHP, System, MODX, and MySQL date/timezone settings must all agree. There's some good information on this issue here. If you can't save chunks and snippets with certain kinds of content in them, mod_security may be the culprit. See this page.

Under some circumstances (as yet unidentified), MODX will create the admin Super User on a fresh install with no username and no password. If your install is successful, but you can't log in, this could be your problem. The solution is to edit the modx_users table in PhpMyAdmin. There will only be one user there. Give the user a username but no password.  This will allow you to log in as the admin user using that username and leaving the password field blank. Once you're logged in, go to Security | Manage Users. Right-click on the admin user and select "Update User". Give yourself a new password and you're back in business.

As always, if everything else fails, post a message in the MODX Forums. Be sure to indicate which version of MODX you are using and exactly what the symptoms are.

Weirdness After Moving a Site

Read the note above about using FTP to transfer the individual files. FTP sometimes corrupts or misses files and it will also sometimes fail to overwrite existing files, leaving you with some outdated MODX core files. It's always better to zip up the files, transfer the .zip file, and unzip them on the server.

You should never transfer the .htaccess file when moving a site. If you did, the RewriteBase line in the file may be your problem — it's almost certainly wrong. If the previous site was a localhost install, see the note below on RewriteBase lines for MODX installs in subdirectories on localhost versus remote servers. Also, see the note below about turning off Friendly URLs.

Before digging any deeper, try the following steps (if you can't access the Manager, just skip the steps that require Manager access):

  • Make sure all templates have a <[[base href="[[++site_url]]" /> tag in the <head> section (or <[[base href="[{+site_url}]" /> for MODX Evolution)
  • Clear the site cache in the Manager
  • Turn off the compress_js and compress_css System Settings in the Manager (see the information above on how to do this)
  • Log out
  • Make sure the file is writable
  • Delete all files in the core/cache directory
  • Clear your browser cache and cookies
  • Run Setup

Here's the next thing to try:

  • Make sure the file is writable
  • Back up the file
  • Load the file in a text editor
  • Delete the contents and save it empty
  • Delete all files in the core/cache directory
  • Clear your browser cache and cookies
  • Run Setup
  • Check the file to see if it's filled in

If those steps don't work, here are some other things to try. If Friendly URLs are on, I usually turn them off (actually, I turn them off before moving or upgrading a site). If you can access the Manager, go to System | System Settings and type friendly in the search box at the upper right. Set the Use Friendly URLs setting to "No". Then, rename the .htaccess file in the MODX root directory to ht.access (or something else). If that fixes things, it's likely that there's a problem with the RewriteBase line in the .htaccess file. For a localhost install in a subdirectory, the subdirectory name is usually necessary in the rewrite base line (RewriteBase /subdirectoryname/. On a remote server, however, it's almost always: RewriteBase /

The next thing to do is to check the paths in the file, (in Revolution) the config.core.php files, and the path in the modx_workspaces table. See the information above on how to do that.

You can also try Everett Griffiths excellent diagnostic script. You can find it here.

As always, if none of that works, consult the MODX Forums.

Weirdness After Updating MODX

A number of things can go wrong when you update MODX. See the note above about using FTP to transfer the individual MODX files. See this page for a description of how I upgrade MODX sites.

If you have tried to upgrade from MODX version 1.x or earlier (MODX Evolution) to version 2.0 or later (MODX Revolution), that's your problem. There is no direct upgrade path at present from Evolution to Revolution. See this page for more information.

If you have upgraded from MODX Revolution version 2.1 or earlier, see these notes .

Try these steps if you haven't already:

  • Delete all files in the core/cache directory (Revolution)
  • Clear your browser cache and cookies
  • Run Setup (Install in MODX Evolution)

Next, try turning off the compress_js and compress_css System Settings as described above.

Make sure that all your MODX extras are up-to-date (TinyMCE is a common culprit). Sometimes it's necessary to uninstall and remove all versions, then download and re-install the extra. Note that if you have installed multiple versions of an add-on (as a result of upgrading the add-on), every time you remove one, you'll see the previous one in Package Manager, so it may take several iterations to remove them all.

Sometimes, a snippet or plugin is incompatible with the new version of MODX and hasn't been updated yet. To find out, start by disabling all plugins. Edit each plugin, check the "disabled" checkbox, and save it. When all plugins have been disabled, delete all files in the core/cache directory and check the site. If that fixes things, you know that one of your plugins is bad. Re-enable them one at a time to find out which one is breaking the site.

Plugins are the most likely cause of your problems because they often execute on every page load, but if the front end of the site is still broken after disabling all plugins, try disabling snippets by putting a space between the opening and closing brackets in your main template. The snippet tag will be displayed on the page, but the snippet won't execute.

As always, if none of that works, consult the MODX Forums.

New Weirdness on an Existing Site

By far the most common complaint here is Resources missing from the Resource tree after making changes to the permission system. If you hide Resources by putting them in a Resource Group and connecting that Resource Group with a User Group, you can easily hide them from yourself. Don't panic, the Resources are still there. One solution is to add yourself to all User Groups with a role of admin Super User. The other solution (if you're using an up-to-date version of MODX Revolution) is to edit your profile and make yourself a "sudo" user. In Security | Manage Users, right-click on your user record and select "Update User". Check the "Sudo user" checkbox at the upper right, then click on the "Save" button. On the Security menu, Flush all Permissions, then Flush all Sessions. When you log back in, the Resources should be back.

If the Manager has gone weird on you and you haven't done anything that might cause it, the most likely problem is a corrupted cache file. Log out, if you can, then:

  • Delete all files in the core/cache directory (Revolution)
  • Clear your browser cache and cookies

If things are still wacky, try turning off the compress_js and compress_css System Settings as described above.

As always, if none of that works, consult the MODX Forums. Be sure to specify the version of MODX you're using and what the exact symptoms are.


My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting

  —  Bob Ray