FAQs & Troubleshooting

Common questions and quick fixes for MODX 3. For deeper troubleshooting, see the topic-specific pages below. If you still need help, ask in the MODX Community or Slack.

Related troubleshooting¶

• Troubleshooting Installation
• Troubleshooting Upgrades
• Troubleshooting Package Management
• Troubleshooting Security
• CMP Development FAQs & Troubleshooting

1. MODX 101¶

1.1. What is MODX / MODX Revolution / MODX Evolution?¶

MODX (also called MODX Revolution) is the actively developed CMS documented here. Current releases are 3.x. See An Overview of MODX for concepts.

MODX Evolution is a separate, older 1.x product line. It is not covered by these 3.x docs. Sites still on Evolution need a migration project; there is no official one-click upgrade path. Historical notes live under Upgrading from Evolution.

If you are moving from Revolution 2.x to 3.x, start with Upgrading from 2.x to 3.0.

1.2. What PHP / server version do I need?¶

See Server Requirements. Current MODX 3.x (3.2 and later) requires PHP 8.1 or higher. MODX 3.0 originally allowed PHP 7.2+; that floor was raised in 3.2.

1.3. What different tags can I use? What is [[*pagetitle]], [[Wayfinder]], etc.?¶

See Tag Syntax. Resource fields you can use in tags are listed under Resources.

2. The Manager¶

2.1. Help! Where did the sidebar / resource tree go?¶

You probably collapsed it. There is a small arrow on the left edge of the screen (see this image). Click it to bring the tree back. Refresh the page if the tree stays empty after expanding.

2.2. How can I change which resource fields are visible when editing?¶

Use Form Customization to hide, rename, or rearrange fields on the Resource create/update screens (and to limit rules to certain user groups or templates).

2.3. What do modDocument / modWeblink / modSymLink / modStaticResource mean?¶

They are the class names for the built-in Resource types (in 3.x they live under the MODX\Revolution\ namespace; short names are still commonly used). All appear in the Resource Tree:

• Documents (class modDocument): normal pages with content. People often say “Resource” when they mean a Document.
• Weblinks: redirect to another Resource or an external URL
• Symlinks: reuse another Document’s content at a different URL
• Static Resources: content comes from a file on the filesystem

2.4. What is the difference between a Resource and a Document?¶

Technically, a Resource (modResource) is the abstract base; a Document (modDocument) is the usual HTML page implementation. In everyday use, “Resource” often means “that page in the tree,” which might be a Document, Weblink, Symlink, or Static Resource.

2.5. I'm locked out of the manager / forgot my password¶

See Resetting a User Password Manually.

2.6. I get a 500 Internal Server Error in the manager¶

Try these first:

1. Clear or rename core/cache/ (a corrupt cache is a frequent cause).
2. Open the manager in a private/incognito window (rules out bad cookies/sessions).
3. Confirm PHP meets Server Requirements for your MODX version.
4. Check core/cache/logs/error.log for the real PHP error.

More install-time cases are covered in Troubleshooting Installation.

2.7. The manager is blank / shows “undefined” / broken layout¶

Often caused by failed JS/CSS loading or a bad cache. Clear core/cache/, hard-refresh the browser, and see the community checklist: Blank manager with undefined message. Also review Troubleshooting Installation (including disabling compress_js / compress_css if asset URLs are failing).

3. Frontend and cache issues¶

3.1. Blank frontend pages that work again after clearing the cache¶

On some hosts (notably certain cloud/shared setups), file locking when writing cache files can leave you with blank pages or 500s after saving until you wipe core/cache/.

In core/config/config.inc.php, disable flock by adding use_flock to $config_options and setting it to false:

$config_options = array(
    'use_flock' => false,
);

(Merge with any existing $config_options entries rather than replacing them.)

3.2. A Snippet or Plugin does nothing¶

Confirm it is actually installed and enabled (Extras → Installer / the Elements tree), that the tag name matches, and that you cleared the cache after installing or editing it. Cached pages will keep serving old output until cleared.

4. Upgrading¶

4.1. How do I upgrade within 3.x, or from 2.x to 3.x?¶

Follow Upgrading MODX. For any move from 2.x to 3.x, also read Upgrading from 2.x to 3.0 before you start: class namespaces, processors, the core path, and PHP requirements all change. Remember that 3.2+ needs PHP 8.1+.