Troubleshooting
What to do when an installation of Exponential 6 does not work. First make sure every requirement is met (Requirements): the setup wizard's system check, and the SystemCheck step of exp:install and the kickstarter, name most problems with their fix.
Where to look
| Log | What it holds |
|---|---|
| var/log/setup.log | the steps of the setup wizard and the installers, with a hint beside known problems |
| var/log/kickstart.log | every kickstarter and exp:install run, passwords masked |
| var/log/error.log, var/log/warning.log | errors and warnings of the running site |
| var/log/exp-install-<date>.ini | the configuration exp:install used, passwords masked |
Debug output at the bottom of every page helps during the install; switch it off again on a public site. In settings/override/site.ini.append.php:
[DebugSettings] DebugOutput=enabled
Symptoms and fixes
| Symptom | Cause and fix |
|---|---|
| Every address shows the setup wizard | CheckValidity is still true: the install did not finish. Finish the wizard, or run the kickstarter or exp:install. |
| "The site is being set up" (503) | A wizard is running in another browser (the hold ends with its last page or 30 minutes after its last request), or a kickstarter run is rebuilding the database. If nothing runs: php bin/php/maintenance.php status, then off. |
| The wizard skips pages or shows values you did not enter | A kickstart.ini is in the installation root. Move it away. |
| The system check fails on directory permissions | Run the chmod and chown commands the page prints, then Next. |
| exp:install: "This directory already holds an installation" | Add --force only if you mean to replace it; without --apply it checks and changes nothing. |
| exp:install or the kickstarter ran but installed nothing | Without --apply both are a dry run (exp:install ends with "dry run, nothing changed"). Add --apply. |
| kickstart.ini values are ignored | Whitespace before sections or keys, a missing Continue=true, or a stale var/cache/ini/kickstart-*.php. |
| Kickstarter: "The database file name is not valid" | SQLite needs a file name ending in .db, .db3, .sqlite or .sqlite3, in [database_init] and [site_details] Database. |
| Kickstarter: "--start-step=... cannot work" | A run cannot resume an earlier one. Fix the cause and run from the start. |
| MariaDB or MySQL: the database "cannot be used" because of its character set | Create the database with CHARACTER SET utf8mb4. |
| PostgreSQL: pgcrypto is missing | CREATE EXTENSION pgcrypto; in the database, by its owner or a superuser. |
| After switching the database engine no page loads | DatabaseImplementation in settings/override/site.ini.append.php still names the old engine. |
| SQLite: "database is busy: the transaction could not start within N s" | Another write held the lock for the whole SQLiteTransactionWait. Nothing was written; retry, or raise the setting, below the request timeout. |
| 404 for every page under Apache | .htaccess is missing or not read (AllowOverride All), or mod_rewrite is off. ./console exp:setup:status says which; ./console exp:setup:htaccess --apply copies the file. |
| "FAIL: .htaccess exists and differs" or the same for config.php | The file has changes of its own. Read the diff; --force --apply replaces it after a backup to var/backup/setup/. |
| A white page or error 500 | Read var/log/error.log; check php -v and that vendor/ exists (composer install). The web PHP may lack an extension the command line PHP has. |
| A change does not show under Velocity | The workers keep the old code: php bin/php/console exp:velocity deploy, or restart and then cache clear --apply. |
| Scheduled content and notifications never go out | The cron job does not run: php bin/php/console exp:installcrontab --show, then --add --apply. |
| The administrator password is lost | As root: php bin/php/resetuserpassword.php -u admin -g --allow-root-user. Otherwise authorize with another administrator (-a <login> -ap <password>). |
More: Troubleshooting in the installation book, with every stage from Composer to signing in, and Repairing an installation. Where to ask: Getting support.
Contributors
- Svitlana Shatokhina
- Geir Arne Waaler
- Graham Brookins Updated Maintainer
Comments
Add a comment