Tracking MODX Error Message to their Source

Sometimes, when you see an error message reported on the screen or in the error log, you’ll get information about where the message is coming from. In other cases, though, MODX logoall you’ll get is the error message. In this article, we’ll look at some tricks for finding the offending file and the code that’s printing the error.

Plugins make this process challenging because they seldom display errors on the screen. They place an error in the MODX Error Log that you might not see until much later, by which time there may be many copies of the error message.


Requirements and Recommendations

To use the method described in this article, you’ll need a code editor than can do multi-file searches, preferably searches of all files in a project or at least all files in a directory. I use PhpStorm, which can do all of the above, plus regular expression searches, but most decent code editors will work, such as NetBeans, PhpEd, and even the free Notepad++ editor (for Windows). You’ll also need local copies of the MODX files, unless you have shell access and know how to use grep.

Most of the time, what you’re looking for will be in the core directory, though not always. If you don’t have a local copy or MODX, you can compress, download, and extract the core directory. That will give you a good chance of finding what you need.

With PhpStorm, and some other editors, you can create a project based on a whole MODX site. The advantage of this is that PhpStorm will take a minute or so to index all the files and their contents, making searches very fast. On my very large development site, PhpStorm will find all occurrences of $modx->lexicon (over 10,000 instances), in about 10 seconds. Finding something with only four instances take less than 2 seconds.

The ideal setup is a localhost install of XAMPP with one or more complete MODX sites installed in directories under the xampp/htdocs directory. Wamp and Lamp are also options, but in my experience, people seem to have fewer problems with XAMPP. XAMPP also has the advantage of being available as an installable package for Windows, OS X, and Linux.

Error Messages

Suppose you see this error in the error log:

[code language=”html”]
[2015-08-23 17:45:59] (ERROR @ /addons/manager/index.php) [StageCoach] No staged Resource found with ID 12

The message includes the name of the extra that logged it (StageCoach). It doesn’t, however, include the file or line number. Worse yet, the error is almost certainly not in the index.php file. Searching the file for the error message won’t help, because it’s not there. Even if you guessed that the problem was in the stagecoach plugin, searching that file file for the error message would fail.

Worse yet, some extras will log messages that don’t include the name of the package, and often as in this case, the name of the file won’t be much help because it won’t be the file that logged the message. The reason is that the message is a lexicon string and the file that logged it will only include the key for that lexicon string, which may or may not make it clear what the message would be.

We can usually still find it, though, with an intelligent search.


Finding the Code that Logged an Error

The trick is to search the whole MODX core for the text of the error message (or a selected part of the message). The first step is to copy a unique part of the error message. In our example, we don’t want to copy the actual ID (12) because it’s likely a variable that might change. We also don’t want to copy the “[StageCoach] part of it, because that won’t change in different languages and it’s unlikely to be part of the error message. That leaves us with a search for No staged Resource found with ID.

If the error message is *not* a lexicon string, you may find the code that’s logging it immediately with this step. That’s not the case with our example and most decent extras will use lexicon strings for their error messages, so we have to go a little further.

In this case, we get one hit from our search. It’s the language file for StageCoach under the core/components directory. If we didn’t know what extra threw the error, we do now. The line in the file is:

[code language=”php”]
$_lang[‘stagecoach_no_resource’] = ‘No staged Resource found with ID’;

Now we know the actual lexicon key for our error message: stagecoach_no_resource. Next, we do a search for that key, again in the core directory (though we could speed things up a bit by just searching core/components/stagecoach, since we know that extra is the culprit). A search for stagecoach_no_resource also has two hits. One is the file we already found. Not surprisingly, the other hit is in the StageCoach plugin file: stagecoach.plugin.php.

[code language=”php”]
if (empty($stagedResource)) {
$modx->log(MODX::LOG_LEVEL_ERROR, ‘[StageCoach] ‘ .
. ‘ ‘ . $stageID) ;


This is the line that’s logging the error and we can look at the code to make a guess about what’s causing the error.


You might be tempted to alter the file that’s logging the error while trying to debug it. If it’s a class file (it will have “class” in the file name) or a processor, this will probably work. If, as in this case, it’s a plugin or snippet file, though, the code MODX uses is actually in the database. Any changes to the file will have no effect. You’d have to modify the plugin or snippet code in the Manager instead.


It’s Not Always That Easy

I chose the example above because there’s only one lexicon string that matches the error message, and only one place that the lexicon key is used. It doesn’t always work out that way. For more generic error message like File Not Found, you might get a lot of hits (in this case, about 40). It can help a lot to always make it a case-sensitive search. With File Not Found, a case-sensitive search turns up only 7 hits.

If you get multiple hits for the first step, remember that the message is most likely a lexicon string. That means that we only care about the hits in lexicon files, which always end in .inc.php. Look at the directories the lexicon-file hits are under and think about which extras or MODX methods might have been running at the time the error was logged.

Lexicon Keys in Other Directories

We’ve been searching in the core directory exclusively. That almost always makes sense for the first search, because all the lexicon files are there. The code that logged the error, though, could be somewhere else. If the Manager itself logged the error, the code might be in the manager directory. In rare cases, the code might be in the assets directory. In very rare cases, it might be somewhere else.

Start with the core directory. If you get no hit on the first search, your search string is probably bad. Some error messages get put together in parts. Consider, for example, this error message:

[code language=”html”]
The file somefile.php could not be found.

The somefile.php could be from a placeholder in the middle of the lexicon string, or there may be separate strings for The file and could not be found. In other words, what you’re looking for may look like this:

[code language=”php”]
$_lang[‘mc_file_nf’] = ‘The file [[+filename]] could not be found

or this:

[code language=”php”]
$_lang[‘mc_the_file’] = ‘The file`;
/* possibly more lexicon strings here */
$_lang[‘mc_nf’] = ‘could not be found’;

If you have the option of regular expression searches, you could search for one of these two patterns:

[code language=”html”]
^.*The file.+could not be found
^.*The file[\s\S]+?could not be found

The first search pattern finds cases where the two parts are on a single line, as in the first example above. The .+ matches any string of characters except a line break (the ^ matches the beginning of a line, and the .* matches 0 or more characters). The second search pattern performs a multi-line search, because [\s\S] matches any character, including a line break, so it will find two separate lexicon strings even if they are on separate lines, whether they are next to each other, or not. The second search will be much slower, so try the single-line version first. Also, be aware that since the order of the lines in a lexicon file doesn’t matter, in the multi-line case, the lexicon strings might not be in the same order as they appear in the error message. This is very unlikely, but if everything else fails, try reversing the order in the multi-line pattern:

[code language=”html”]
^.*could not be found[\s\S]+?The file

When using regular expression (regex) searches, you may get more hits than you want. Again, it may help to make the search case-sensitive. If your regex is malformed, you won’t get any hits at all, so be careful when you create it. Here’s another version of the patterns above, but with parentheses around the two search strings. This will slow down the search, but it may make it easier for you to follow the patterns:

[code language=”html”]
^.*(The file).+(could not be found)
^.*(The file)[\s\S]+?(could not be found)

Here’s a plain language description of the two regex search strings above:

1. Find the beginning of a line, followed by 0 or more instances of any character but a line break, followed by ‘The File’, followed by 1 or more instances of any character but a line break, followed by ‘could not be found’.

2. Find the beginning of a line, followed by 0 or more instances of any character but a line break, followed by ‘The File’, followed by 1 or more instances of any character including a line break, followed by ‘could not be found’. The question mark makes the middle part “non-greedy,” so it will stop at the first match.


Sometimes It’s Way Worse

You may have already seen this error message in the MODX Error Log:

[code language=”html”]
[2015-08-24 00:47:51] (ERROR @ /addons/manager/index.php) “ is not a valid integer and may not be passed to makeUrl()

A quick search of the core for is not a valid integer and may not be passed to makeUrl turns up two hits. One is the MODX error log (no surprise, we’ve already seen that one). The second is in the modX object’s class file: modx.class.php. Notice that neither one is in manager/index.php — that file just ‘includes’ the modX class file. (It doesn’t look right, but the actual name of the class for the $modx object is modX.)

In this case, we’ve found our error message immediately, because it’s not a lexicon string. That error message is hard-coded into the modx.class.php file. Now what?

A look at the code tells us what’s going on, but it’s not much help. Somebody, somewhere has called $modx->makeUrl() like this:

[code language=”php”]
$url = $modx->makeUrl($docId, ‘…’);

where the variable $docId is 0 or not a valid integer (usually, it’s an empty string).

The obvious next step is to search for makeUrl, but in my MODX project, that turns up 614 hits. Because it’s very unlikely that MODX itself produced the error, you can limit the search to the core/components directory, but in my project, that still produces 218 hits. It’s better, but still not great. You can look at the file names and try to guess which extra was active at the time of the error, but it won’t be easy. Recently installed extras are the most likely culprits.

You might think that MODX should identify the snippet or plugin that called makeUrl(), but it can’t. It knows the method has been called, but it has no way of knowing where the call came from.

If you are an extra developer. You can do your users a great kindness by testing the value of the first argument before calling makeUrl(). The code would look like this:

[code language=”php”]
$docId = $someVariable;
if (! intval($docId)) {
$modx->log(modX::LOG_LEVEL_ERROR, ‘[MyExtra line ‘ . __LINE__ . ‘] makeUrl() called with invalid resource ID’);
$modx->makeUrl($docId, "", "", "full");

The line number may be off by a few lines, but you’ll still save users trying to find the error a whole lot of time and frustration.


Coming Up

In the next article, we’ll look at what to do when you encounter the MODX White Screen of Death, when a MODX snippet produces a completely blank screen.


For more information on how to use MODX to create a web site, see my web site Bob’s Guides, or
better yet, buy my book: MODX: The Official Guide.

Looking for quality MODX Web Hosting? Look no further than Arvixe Web Hosting!

Tags: , , , | Posted under MODX, MODX | RSS 2.0

Author Spotlight

Bob Ray

Bob Ray is the author of MODX: The Official Guide and over 30 MODX add-on components. He hosts Bob's Guides, a source of valuable information for MODX users, and has been very active in the MODX Forums with over 19,000 posts.

Leave a Reply

Your email address will not be published. Required fields are marked *