FAQs & Troubleshooting

Common questions and quick fixes for MODX 3. Still stuck? 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?¶

Names on forums and in search results often mix product lines. Short map:

• MODX / MODX Revolution 3.x — the CMS documented here; current releases are 3.x. Concepts: An Overview of MODX.
• MODX Revolution 2.x — the previous major Revolution line. Many production sites still run it. Upgrading to 3.x is supported with planning; start with Upgrading from 2.x to 3.0.
• MODX Evolution — a separate, older 1.x product line, not covered by these 3.x docs. Migrating from it is a project; there is no one-click upgrade path. See Upgrading from Evolution.

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

See Server Requirements. MODX 3.x (3.2 and later) requires PHP 8.1 or higher; before 3.2: PHP 7.2.5+ (3.0), PHP 7.4+ (3.1).

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

See Tag Syntax. Resource fields usable in tags are listed under Resources.

2. The Manager¶

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

You probably collapsed it: click the small arrow at the screen's left edge (see this image) to restore the tree. Refresh if it 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?¶

Class names of the built-in Resource types (in 3.x they live under the MODX\Revolution\ namespace; short names remain common). 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?¶

A Resource (modResource) is the base class; a Document (modDocument) is the usual HTML page. In everyday use, “Resource” often means “that page in the tree”: 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. (If the site sets a custom PSR-3 logger via modX::setLogger(), errors go there instead.)

More install-time cases: Troubleshooting Installation.

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

Failed JS/CSS loading or a bad cache. Clear core/cache/, hard-refresh the browser, then check the community checklist: Blank manager with undefined message. Also see Troubleshooting Installation (including disabling compress_js / compress_css if asset URLs fail).

3. Frontend and cache issues¶

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

On some hosts (notably cloud/shared setups), file locking while writing cache files can leave blank pages or 500s after saving until you clear 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 existing $config_options entries rather than replacing them.) With use_flock disabled, MODX falls back to lock files under core/cache/locks/ instead of file locking.

3.2. A Snippet or Plugin does nothing¶

Confirm it is installed and enabled (Extras → Installer / the Elements tree), the tag name matches, and the cache was cleared after installing or editing it. Cached pages 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 a 2.x to 3.x move, read Upgrading from 2.x to 3.0 first: class namespaces, processors, the core path, and PHP requirements all change. 3.2+ needs PHP 8.1+.