MODX Installation FAQ

For general installation instructions, look here.

Before looking at the specific issues below, you might want to check the General MODX Weirdness page.

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.

Click on a question to expand the answer

Show All      Hide All

I get a blank page after the install. What's wrong?

This is a problem that has multiple causes. Here are some possibilities:
  • Installing MODX Revolution over an earlier version
  • core/cache directory is not writable
  • database password contains a quotation mark or other illegal character
  • Permission issue with MODX directories and files
  • Not enough memory for proper install (see "out of memory" below)
  • Very old version of MySQL or PHP
Things to try:
  1. Make sure your memory_limit is at least 64M
  2. Make sure the following directories are writable:
    • / (MODX root directory)
    • /core/packages
    • core/cache
    • core/export
    • /manager
    • /connectors
  3. Create an empty file: "/core/config/" and make it writable.
  4. Use the "Regular" version of Revolution instead of the "Advanced" version.

I get a blank page or an "unable to load page" error when I try to run setup. What's wrong?

This is often caused by having PHP's safe_mode on. See this link for more information. Another possibility, if you are using XAMPP, is that JSON is not enabled. Look for the php-pear.ini file and uncomment the following line (remove the semicolon):
See also the item below about the timezone warning. Sometimes the timezone warning isn't on the screen long enough to read.

I've upgraded MODX and the Manager is all messed up. What now?

First, did you run an upgrade install and clear your browser cache and cookies?

If so, it's likely that it's one of these:
  • 1. File and/or directory permissions were changed by the file transfer and MODX can't read or write some necessary files.
  • 2. File permissions issues prevented a new file from overwriting an old one.
  • 3. One or more files was corrupted during the transfer.
  • 4. Trouble with the compress_js System Setting

In the case of #3, log out and edit the modx_system_settings table in PhpMyAdmin. Find compress_js and change the value to 0,then delete the core/cache/system_settings/config.cache.php file and log back in.

I get a blank page for one or more pages on the site. How do I fix that?

I've never experienced this, but other users report that the best way to prevent it is to do all of the following:
  • Create an error page that is not the site_start page and set the error_page System Setting to its ID. The error page is where MODX sends users when the page they request is not found.
  • Create a proper robots.txt file at the root of your site. Look here for more information.
  • Modify the .htaccess file in the site root by uncommenting the code that redirects all visitors to either "" OR "".

Why do I get this error: Fatal error: Call to undefined function mb_strlen() in [filename]?

You need to have the php_mbstring module enabled in your php.ini. Some setups have it disabled by default.

If that's not possible, you can try changing mb_strlen() to just strlen() in the file referenced in the error message.

I'm getting a warning about the system's timezone setting. How can I fix it?

PHP 5.3 requires a timezone setting. There are several possible fixes (use the appropriate timezone for your location). The list of possible settings is here.

Put something like this in your php.ini file:
date.timezone = "America/Chicago"

If you don't have access to php.ini, you can try adding this to your .htaccess file:
php_value date.timezone America/Chicago

If you don't have access to the php.ini file and modifying .htacces gives you an error, you can try putting a line like this in the index.php file in the MODX site root:

If none of these work, you'll need to contact your hosting service.

Note: If you're using XAMPP, you can modify /xampp/apache/bin/php.ini.

I'm getting an error message about PDO or pdo_mysql not being available. What's up with that?

Revolution makes heavy use of xPDO, which is based on PDO, for DB access. The message usually means that pdo is not enabled in the php.ini file. On a local install, find the master php.ini file (PhpInfo() will tell you where it is) and back it up before making any changes. This can't be stressed enough. A messed up php.ini file can bring down your whole web site, so it's important to be able to restore it.

It's hard to give generic advice here on altering php.ini because it depends on your platform, but basically you need to uncomment the line that enables what the error message tells you needs enabling. Uncomment the line by removing the semicolon at the beginning. This is a commmon one:

; change it to:

Then, restart your server.

If the site is on a remote server, ask your host to enable pdo.

I'm getting an Internal Server 500 error on my MODX install. What do I do?

This is a fairly generic error so there's no one thing that causes it.

One common possibility is file permissions. If your host uses suExec or suPHP, the permissions on folders should be 755 and files should be set to 644. Usually this is done by going to cPanel (or the equivalent) at your host and clicking on "File Manager." In File Manager, you navigate to the file or directory you want to change (your site will normally be under public_html). You'll see the permission numbers on the right as you go. When you get to the target file or directory, click on its name, then on "change permissions." An even easier method, if it works on your host, is to use the free FileZilla FTP program which allows you to set permissions for all files and folders recursively.

Another, less common, possibility is a bug in the MODX SearchHighlighting Plugin. Disabling the plugin will solve the problem.

On some hosts, having a php directive in the .htaccess file will generate a Server 500 error.
php_flag zlib.output_compression On
The solution is to comment out the php_flag lines with a '#' character at the beginning:
#php_flag zlib.output_compression On
Having an unpublished error document on the MODX site can also cause a 500 error under some circumstances.

Another possiblity is having a "rewrite engine on" statement in an .htaccess file and another .htaccess file in a directory below that one that also contains the same line.

If you get a 500 error when you turn on Friendly URLs with XAMPP on localhost, make sure you have these in your xampp/apache/conf/httpd.conf (without the # comment token at the beginning):
LoadModule rewrite_module modules/
AllowOverride All
If you are getting this error on a site you moved by exporting and importing the SQL, be sure you have enabled DROP TABLE and CREATE TABLE in the export.

I've upgraded MODX Revolution from a much earlier version and I keep ending up back at the login screen. How can I fix that?

There are three deprecated system settings that need to be deleted from the modx_system_settings table in the database: session_name, session_cookie_path, and session_cookie_domain. Once you've removed them in PhpMyAdmin, delete the core/cache/config.cache.php file, clear your browser cache and cookies, and login again.

I've moved my site to another server. Why can't I install the packages I've downloaded?

This usually means that you need to edit the modx_workspaces table in the MODX database using PhpMyAdmin and update the path for the default workspace.

I'm getting an "out of memory" message during the install process or I'm seeing weird behavior after the install. What can I do?

MODX tries to increase the memory limit if you are short, but it doesn't always work. Being short of memory should generate an error during install, but sometimes the install will appear to complete normally even though there wasn't enough memory to do the job right. This can result in all kinds of weird errors when you try to use MODX. The solution is to increase your memory_limit and rerun the install.

Increasing the amount of memory depends on your host. You may be able to add this php directive in your .htaccess file:
php_value memory_limit 128M
If that doesn't work, you may be able to edit or add a php.ini file and change the memory limit:
memory_limit = 128M
Note that the server has to be restarted for the changes in memory_limit to take effect. In some cases, you'll have to ask your hosting service to increase your memory limit (or change hosts).

The install ran perfectly, but I can't log into the Manager. I'm positive that my username and password are correct. What now?

If I had a dime for every user who said that but had mistyped or misremembered one or the other . . . That said, it could mean that MODX ran out of memory during the install. See "out of memory" above. Also, see the thread here.

Why does checking the database connection fail during install even though I know my credentials are right?

  • Be sure to use "localhost" as the database server name. It's almost always correct.
  • If MODX has trouble creating the database, you may have to do it yourself. Make sure to create a user and give the user full rights to the database. That user's username and password are what you need for the database connection form during the MODX install — not your MODX username and password.
  • Some hosts add a prefix to the database name and/or database username so the names you entered when you created the DB/User may not be the real ones.
  • The next best guess here is either a too-old version of PHP, a PHP/MySQL version mismatch, or a misconfigured or disabled PHP or MySQL install.
  • Also possible are a non-standard port, or a name other than "localhost" for the database server.

I've installed MODX over an existing non-MODX site, why do I keep seeing either the old site or an index of the root directory instead of my MODX site in the front end?

MODX uses an index.php file in the root of the site to dispatch the user to its various pages. You probably still have an index.html or index.htm page in the site root. You need to rename it or tell Apache to give index.php priority as the index page. Look here or add this code to the .htaccess file in the MODX root directory:
DirectoryIndex index.php

I've installed MODX Revolution and I get a 404 "Page not Found" error in the front end. Why is this happening?

Unlike MODX Evolution, Revolution is installed with no content. You need to create a document resource and make it the home page.

I've installed MODX Revolution and there is no Rich Text Editor (e.g. TinyMCE). Where is it?

Unlike MODX Evolution, Revolution is installed with no snippets or plugins. You need go to System | Package Management and click on "Download Extras." Then download TinyMCE and any other add-on componenents you need for your site. Then install them by right clicking on them and selecting "Install."

When I go to Package Manager in MODX Revolution, and click on "Download Extras," I get to the repository, but there are no packages listed. Why not?

In order for the repository to show packages, you need to have cURL enabled on your server. If you are using XAMPP locally, cURL is disabled by default (and may be again if you update XAMPP).

Go to Reports | System Info and click on the "view" link next to PhpMyAdmin. Find the location of your php.ini file. In a text editor, edit that file and uncomment the following line (remove the leading semicolon):
Save the file and then stop and restart Apache.

I've installed MODX Revolution and there are no snippets (e.g. Wayfinder, Ditto, etc.) What's up?

Unlike MODX Evolution, Revolution is installed with no snippets or plugins. You need go to System | Package Management and click on "Download Extras." Then download TinyMCE and any other add-on componenents you need for your site. Then install them by right clicking on them and selecting "Install."

I've installed MODX Revolution and the Components menu is missing. Is this normal?

Yes. That spot is available for third-party components that want to add custom Manager pages. You install the components in System | Package Management.

I have weird behavior in MODX after the install that isn't covered here. What now?

If you have moved your site, be sure to do an Upgrade Install at the new site. Try clearing your browser cache and cookies and, if you can access the MODX Manager, clear the MODX cache as well. If you can't access the Manager, go to the core/cache directory and delete everything in it.

Sometimes, one or more MODX files is corrupted in download or upload. MODX has a lot of files and this happens more often than you might think. If everything else fails, try downloading and installing again.

I can't save some things in the Manager. When I try to save (happens most often with templates and snippets), MODX freaks out. What's wrong?

This is often a mod_security problem that has to do with how MODX objects are saved to the database. Look here for more information on making the problem go away.

None of that helped me. What do I do now?

First, check out the Installation troubleshooting page here. If nothing there helps you, ask a question on the MODX Forums. There's a good chance that someone there can help you sort it out.

How did you create this marvelous FAQ?

The FAQ uses some JavaScript code from and is extremely easy to create and maintain in MODX thanks to the EZfaq Snippet, created by (ahem) me. Go here to see the EZfaq tutorial.


My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be 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