You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
note: "This page hasn't been updated in a while, and could use a good review."
7
6
---
8
7
9
-
This document aims to get you started with common issues / questions with MODX Revolution by either answering it, or pointing you to the right resources. It is by no means exclusive, and a good search on the forums and this documentation may find more resources for what you're looking for. In all cases - if you can't find what you need, do ask in the [forums](http://forums.modx.com) or on IRC: irc.freenode.org channel: #MODX.
8
+
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](https://community.modx.com) or [Slack](https://modx.org).
10
9
11
-
The questions numbering represents nothing but that - a number to indicate what question you're looking at to help scanning through.
10
+
## Related troubleshooting
12
11
13
-
This is a documentation stub, and could use your help to complete! If you don't have access to edit this page, [please post anything you would want to see added or updated in this topic on the forums](http://forums.modx.com/thread/72123/faqs-troubleshooting-on-the-rtfm).
14
-
15
-
This document will always be a work in progress as new features are added / changed, and it could use your help in keeping it structured and up to date! If you do not have access to editing this document, [please post anything you would want to see added or updated in this topic on the forums](http://forums.modx.com/thread/72123/faqs-troubleshooting-on-the-rtfm).
16
-
17
-
## Table of Contents
18
-
19
-
FAQs and/or Troubleshooting on specific subjects elsewhere:
-[CMP Development FAQs & Troubleshooting](extending-modx/custom-manager-pages/troubleshooting)
31
17
32
18
## 1. MODX 101
33
19
34
-
### 1.1. What is MODX Evolution, and what is MODX Revolution? What's the difference?
35
-
36
-
MODX Evolution is the legacy code and are the 1.x versions. It has powered hundreds of thousands of websites in the past five years and is what has shaped MODX.
20
+
### 1.1. What is MODX / MODX Revolution / MODX Evolution?
37
21
38
-
MODX Revolution is a complete rewrite of MODX Evolution which shares the same ideas but is based on xPDO, a database abstraction layer, and finally saw daylight in 2010.
22
+
**MODX** (also called **MODX Revolution**) is the actively developed CMS documented here. Current releases are **3.x**. See [An Overview of MODX](getting-started/what-is-modx) for concepts.
39
23
40
-
There are three kinds of MODX products at this point:
24
+
**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](getting-started/maintenance/upgrading/evolution).
41
25
42
-
- 0.9.6.x – the original code base that started with it's first production/stable release as version 0.9.0 at the end of October 2005. _No longer supported, and you REALLY should update to the latest Evolution version. Exploits founds in 0.9.6.x have long been fixed!_
43
-
- Evolution 1.x – a cleaned up and refined distribution of 0.9.6.x with conventions and terminology more in line with our totally rewritten Revolution release.
44
-
- Revolution 2.x – a fully object oriented and completely new branch that's been in development for more than 3 years that addresses limitations found in the original code base such as having a truly recursive parser and eliminating the 5,000 document ceiling.
26
+
If you are moving from **Revolution 2.x to 3.x**, start with [Upgrading from 2.x to 3.0](getting-started/upgrading-to-3.0).
45
27
46
-
Further reading:
28
+
### 1.2. What PHP / server version do I need?
47
29
48
-
- "The Evolution of a Revolution" <https://modx.com/about/blog/the-evolution-of-a-revolution/>
49
-
- "What are the basic differences between Evolution and Revolution?" <https://modx.com/revolution/product/faq/#q1>
50
-
- There's a number of big topics on the forums as well discussing evo and revo which may be interesting if you're looking for more in-depth discussing of the differences. As Revolution has been over three years in development, do check out the date something was posted to be sure they are still relevant.
30
+
See [Server Requirements](getting-started/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.
51
31
52
-
### 1.2. What different tags can I use? What is `[[*pagetitle]]`, `[[Wayfinder]]` etc?
32
+
### 1.3. What different tags can I use? What is `[[*pagetitle]]`, `[[Wayfinder]]`, etc.?
53
33
54
-
Check out the [Tag Syntax](building-sites/tag-syntax"Tag Syntax") documentation. You can find resource fields you can use in Revolution on the [Resources Documentation](building-sites/resources"Resources").
34
+
See [Tag Syntax](building-sites/tag-syntax). Resource fields you can use in tags are listed under [Resources](building-sites/resources).
55
35
56
36
## 2. The Manager
57
37
58
-
### 2.1. Help! Where did the sidebar go?
38
+
### 2.1. Help! Where did the sidebar / resource tree go?
39
+
40
+
You probably collapsed it. There is a small arrow on the left edge of the screen ([see this image](subtlearrow.PNG)). Click it to bring the tree back. Refresh the page if the tree stays empty after expanding.
41
+
42
+
### 2.2. How can I change which resource fields are visible when editing?
59
43
60
-
You probably hid it at some point. There's a subtle arrow on the left side of the screen ([see this image](subtlearrow.PNG)) that you can click to bring it back. In some cases you will need to refresh the page for the contents of the sidebar to load properly.
44
+
Use [Form Customization](building-sites/client-proofing/form-customization) to hide, rename, or rearrange fields on the Resource create/update screens (and to limit rules to certain user groups or templates).
61
45
62
-
### 2.2 How can I modify what resource fields are visible when creating or editing a [Resource](building-sites/resources"Resource")? Is there something like [ManagerManager](https://modx.com/extras/package/managermanager) for Revolution?
46
+
### 2.3. What do modDocument / modWeblink / modSymLink / modStaticResource mean?
63
47
64
-
You can use [Form Customization](building-sites/client-proofing/form-customization"Form Customization") (found under the Security menu) to change the fields. It doesn't offer all of the (Evolution) ManagerManager plugin but comes pretty far.
48
+
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:
65
49
66
-
### 2.3 What does modDocument/ modWeblink/ modSymLink/ modStaticResource mean?
50
+
-[Documents](building-sites/resources) (class `modDocument`): normal pages with content. People often say “Resource” when they mean a Document.
51
+
-[Weblinks](building-sites/resources/weblink): redirect to another Resource or an external URL
52
+
-[Symlinks](building-sites/resources/symlink): reuse another Document’s content at a different URL
53
+
-[Static Resources](building-sites/resources/static-resource): content comes from a file on the filesystem
67
54
68
-
They are the class names of Documents, Weblinks, Symlinks and Static Resources. They are "subtypes" of Resources (class name modResource) and each have their own specific goal. They all show up in the Resource Tree and can appear anywhere in the hierarchy.
55
+
### 2.4. What is the difference between a Resource and a Document?
69
56
70
-
-[Documents](building-sites/resources"Resources") (commonly refered to as Resources, see 2.4 below) are regular pages and have content.
71
-
- A [Weblink](building-sites/resources/weblink"Weblink") redirect a user to a different Resource or an external URL.
72
-
- A [Symlink](building-sites/resources/symlink"Symlink") acts as a copy of a Document
73
-
-[Static Resources](building-sites/resources/static-resource"Static Resource") act like Documents, however their content comes from a file on the filesystem.
57
+
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.
74
58
75
-
### 2.4 What is the difference between a Resource and a Document?
59
+
### 2.5. I'm locked out of the manager / forgot my password
76
60
77
-
Technically, a Resource (modResource) is an abstract object of which a Document (modDocument) is an implementation.
61
+
See [Resetting a User Password Manually](building-sites/client-proofing/security/troubleshooting-security/resetting-a-user-password-manually).
78
62
79
-
Practically both terms are used to indicate the same thing: a Document which holds certain content. Coming from the technical implementation, a [Weblink](building-sites/resources/weblink"Weblink"), [Symlink](building-sites/resources/symlink"Symlink") or [Static Resource](building-sites/resources/static-resource"Static Resource") are also be included when referring to "Resources" as they are also implementations of the modResource class.
63
+
### 2.6. I get a 500 Internal Server Error in the manager
80
64
81
-
### 2.5 I'm locked out! I can't access the manager! Forgot my password and recovery doesn't work!
65
+
Try these first:
82
66
83
-
You're not doomed. [Check out these instructions for Revolution](building-sites/client-proofing/security/troubleshooting-security/resetting-a-user-password-manually"Resetting a User Password Manually").
67
+
1. Clear or rename `core/cache/` (a corrupt cache is a frequent cause).
68
+
2. Open the manager in a private/incognito window (rules out bad cookies/sessions).
69
+
3. Confirm PHP meets [Server Requirements](getting-started/server-requirements) for your MODX version.
70
+
4. Check `core/cache/logs/error.log` for the real PHP error.
84
71
85
-
### 2.6 I am getting a 500 HTTP Internal Server Error
72
+
More install-time cases are covered in [Troubleshooting Installation](getting-started/installation/troubleshooting).
86
73
87
-
If you're experiencing a 500 internal server error in the manager, here are a few things to try that typically resolves most common problems:
74
+
### 2.7. The manager is blank / shows “undefined” / broken layout
88
75
89
-
- Rename or remove the `/core/cache` folder. The cache can sometimes get corrupted.
90
-
- Open an incognito window in your browser. That resolves any cookie-related issues.
76
+
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](https://community.modx.com/t/blank-manager-with-undefined-message/3799/20). Also review [Troubleshooting Installation](getting-started/installation/troubleshooting) (including disabling `compress_js` / `compress_css` if asset URLs are failing).
91
77
92
-
## 3. Frontend Display Issues
78
+
## 3. Frontend and cache issues
93
79
94
-
### 3.1 Blank frontend pages resolved by Clearing Cache
80
+
### 3.1. Blank frontend pages that work again after clearing the cache
95
81
96
-
In Revolution 2.2.5 the way xPDO/MODX write cache files has been re-factored. If you are having issues with blank frontend pages that are resolved after clearing the site cache, you could try setting _use\_flock_. This should help with RackSpace Cloud hosting, GoDaddy hosting, and some other providers.
82
+
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/`.
97
83
98
-
Also, if after saving a resource/template the browser only gives an error message 500 when loading the manager. And if the problem can then be solved by deleting the entire cache directory content via FTP, then this indicates a flock issue.
84
+
In `core/config/config.inc.php`, disable flock by adding `use_flock` to `$config_options` and setting it to `false`:
99
85
100
-
In your MODX config file add the setting _use\_flock_ in your $config\_options array, and set it to false.
86
+
```php
87
+
$config_options = array(
88
+
'use_flock' => false,
89
+
);
90
+
```
101
91
102
-
See Original Post: <http://forums.modx.com/thread/78611/core-cache-file-locks-and-will-not-update#dis-post-434053>
92
+
(Merge with any existing `$config_options` entries rather than replacing them.)
103
93
104
-
### 3.2 General Snippet Problems
94
+
### 3.2. A Snippet or Plugin does nothing
105
95
106
-
If you find a snippet and/or plugin isn't working properly despite the correct code, double check that it has been installed.
96
+
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.
107
97
108
-
## 4. Frontend Display Issues
98
+
## 4. Upgrading
109
99
110
-
### 4.1 Blank manager pages
100
+
### 4.1. How do I upgrade within 3.x, or from 2.x to 3.x?
111
101
112
-
Perhaps the most complete list of what needs to be checked is described here: <https://community.modx.com/t/blank-manager-with-undefined-message/3799/20>
102
+
Follow [Upgrading MODX](getting-started/maintenance/upgrading). For any move from 2.x to 3.x, also read [Upgrading from 2.x to 3.0](getting-started/upgrading-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+**.
0 commit comments