Troubleshooting MODX Installation

Troubleshooting MODX Installation Getting Started

General Problems

First of all, make sure that:

  • Your eAccelerator is disabled during installation, it can cause problems when handling complex processes. Information on how to disable it is below.
  • Your hosting (server) meets the minimum requirements for installation.
  • Completely clear the core/cache/ directory before starting the installation (if it is not empty); Sometimes incorrect file permissions can cause problems.
  • Clear your browser cache and cookies

If this does not help and your hosting provider has an auto-installer for scripts, try using it.

PDO Error Messages

If you are getting PDO-related error messages during installation, before going through the specific error messages as shown below, make sure your PDO configuration is set up correctly. You can do this by running the following code (replace user/password/database/host with your setup):

<?php
/* Connect to an ODBC database using driver invocation */
$dsn = 'mysql:dbname=testdb;host=localhost';
$user = 'dbuser';
$password = 'dbpass';

try {
  $dbh = new PDO($dsn, $user, $password);
} catch (PDOException $e) {
  echo 'Connection failed: ' . $e->getMessage();
}
?>

If this fails, your PDO installation is not configured correctly.

Common Errors

Here are some common problems you may encounter during installation and how to fix them:

“I get a blank white screen instead of a settings page!”

You probably copied config.inc.tpl to config.inc.php, which is incorrect. Make config.inc.php an empty, writable file.

If you renamed config.inc.tpl to config.inc.php, rename it back to config.inc.tpl and create an empty file named config.inc.php that is writable.

“I clicked Install and got a blank white screen!”

Make sure your memory_limit setting in php.ini is set to at least 64M.

“Unable to connect to database” on the database settings page

One common cause of this problem is that you are using a non-standard port for MySQL. Try pasting this syntax into the hostname field (replacing the data with the host and port of your mysql server):

my.database.com;port=3307

Warning: PDO::__construct() [pdo.–construct]: [2002] Argument invalid (trying to connect via unix://) or “Checking database:Could not connect to the mysql server.”

This means that your MySQL socket is not configured correctly. This can usually be fixed by adding (or updating) your php.ini:

mysql.default_socket=/path/to/my/mysql.sock
mysqli.default_socket=/path/to/my/mysql.sock
pdo_mysql.default_socket=/path/to/my/mysql.sock

Sometimes something doesn’t load, the page crashes, etc. (eAccelerator)

Are you using eAccelerator? In some server configurations this can cause problems. You may need to disable it. You can do this via your php.ini:

eaccelerator.enable = 0;
eaccelerator.optimizer = 0;
eaccelerator.debug = 0;

or in your .htaccess in the modx root directory if your server supports the php_flag server directives:

php_flag eaccelerator.enable 0
php_flag eaccelerator.optimizer 0
php_flag eaccelerator.debug 0

Unexplained Issues in Control Panel (non-eAccelerator)

On some systems, especially shared hosting, you may have issues with the System Settings compress_js and/or compress_css. Go to System -> System Settings and type compress (without quotes) in the search box in the upper right corner. Turn off these two settings, then log out of Control Panel, delete all files in the core/cache directory, clear your browser cache and cookies, and log back in.

If the Control Panel is so broken that you cannot change the settings, see the note below about changing the two System Settings in the modx_system_settings table in the database using PhpMyAdmin.

Resources/Elements/Files tabs are not displayed in the tree

Also, incomplete page output may be caused by data stored in your browser cache. Old versions of javascript and other files used on the client side may cause the resource/element/files tree to be displayed incorrectly. You can check this by logging into the Control Panel using a browser that you have not previously used.

A simple solution: clear your browser cache and log into the Control Panel again.

More complete solution:

  1. Manage menu section – Clear Cache
  2. In Manage – Reset permissions and then End all sessions
  3. This will reset and log you out of the Control Panel
  4. Final step Clear your browser cache

I can’t log into the Control Panel after installation

If you are getting redirected back to the login screen every time, try adding this setting to the .htaccess file in the root of your MODX installation:

php_value session.auto_start 0

Unable to connect to the database server. Check your connection properties and try again. Access denied

Often on shared hosting, if you create a username for your database with an underscore (_), this causes problems. Make sure your database username does not contain an underscore and try again.

More common issues to come…

Control panel outputs as text after installation

The MODX control panel loads compressed CSS and JS assets. Some server configuration. See “JS errors in the manager due to error 4

The Dashboard is displayed in plain text, some elements are missing, or JavaScript 400 errors are returned

If the MODX Dashboard is not loading properly due to 400 errors when trying to load JavaScript code compressed by Google Minify, it is likely due to an incorrect configuration of your server. If this cannot be fixed on the server side, you can manually disable JS and CSS compression as follows:

  1. Log in to your database with PhpMyAdmin and find the table table_prefix_system_settings (table_prefix usually modx).
  2. Find the lines with the keys compress_js and compress_css, set them to 0 and save.
  3. Clear core/cache/ directory.
  4. Clear your browser cache and cookies
  5. Log in to your Control Panel.

This will allow you to use the Control Panel without compressing JS and CSS.

Missing Control Panel items, undefined language strings, or JavaScript 500 errors

  1. Make sure the connectors/ folder has permissions set to 0755

Still having problems?

If you are still having problems, please post information about the error and the server environment on the official forum, we will try to help you solve the problem as soon as possible.

Rate article
MODX 3
Add a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.