Troubleshooting

Most first-install problems are server configuration mismatches, not jekcms bugs. This page is a symptom-first index - find your error, scan the likely cause, apply the one-command fix.

!The Error log screen, with a file selector and a Copy last 30 lines button

If none of these match, check logs/php-errors.log first - jekcms catches and logs virtually every fatal.

500 Internal Server Error

Symptom: Every page - including the installer - returns 500 Internal Server Error.

Likely cause: Apache can't process .htaccess. Either mod_rewrite is disabled or the vhost has AllowOverride None.

Fix:

sudo a2enmod rewrite && sudo systemctl restart apache2

Then edit your vhost (/etc/apache2/sites-available/000-default.conf or similar) and set AllowOverride All inside the <Directory> block for your web root.

Database "Connection refused"

Symptom: Installer step 2 fails with SQLSTATE[HY000] [2002] Connection refused.

Likely cause: MySQL isn't listening on the port you think it is, or a firewall is blocking it. On localhost setups it's often a TCP-vs-socket mismatch.

Fix: Use 127.0.0.1 instead of localhost in the DB host field. localhost tells PHP to use a Unix socket; 127.0.0.1 forces TCP. If your server actually is remote, confirm port 3306 is open:

sudo ufw allow from <webserver-ip> to any port 3306

Login redirects in a loop

Symptom: Admin login succeeds, immediately bounces back to the login screen.

Likely cause: Session cookies aren't being stored. Common triggers: cookie domain mismatch (example.com vs www.example.com), session save path unwritable, or a trailing-slash mismatch between admin URL and canonical URL.

Fix:

sudo chmod 1733 /var/lib/php/sessions

And in config/config.php set SITE_URL to the exact same form (with or without www) that users type in the address bar.

Blank admin page

Symptom: White page, no HTML source, no obvious error.

Likely cause: PHP fatal error with display_errors off. Typically a missing extension the theme or plugin needs.

Fix: Check the error log:

tail -n 50 logs/php-errors.log

The last line will name the exact class/function that failed. Install the missing extension (usually gd, imagick, or intl).

Can't upload images

Symptom: Media library upload spins, then fails with Upload failed.

Likely cause: uploads/ directory isn't writable by the web server user.

Fix:

sudo chown -R www-data:www-data uploads/ && sudo chmod -R 755 uploads/

On shared hosting without root, use your file manager to set permissions on uploads/ to 755.

Featured image shows broken

Symptom: Post displays but the featured image thumbnail is a broken link. URL inspector shows https://yoursite.com/uploads/2026/04/image.webp returning 404.

Likely cause: UPLOADS_URL in config/config.php doesn't match the physical uploads/ path. Common after moving the install to a subdirectory or behind a CDN.

Fix: Open config/config.php and set:

define('UPLOADS_URL', SITE_URL . '/uploads');
define('UPLOADS_PATH', __DIR__ . '/../uploads');

Then clear the cache:

rm -rf cache/*

"Security validation failed"

Symptom: Every admin form submission fails with Security validation failed. Please reload and try again.

Likely cause: CSRF token mismatch. Either the session expired, or the user has two admin tabs open and the newer token invalidated the older one.

Fix: Reload the page (Ctrl+R / Cmd+R). If it happens repeatedly, your session lifetime is too short - raise SESSION_LIFETIME in config/config.php to 7200 (2 hours).

White screen after switching theme

Symptom: Applied a new theme, front-end now shows a blank white page.

Likely cause: The theme archive is missing a required template - typically index.php or single.php.

Fix: Revert to the previous theme via CLI:

php cli.php theme:activate default

Then re-examine the theme you tried to apply - it needs at minimum index.php, single.php, page.php, and style.css per the theme spec.

AI content assist "Invalid API key"

Symptom: OpenAI-powered features (content assist, SEO suggestions) return 401 Invalid API key even though the key works when you paste it into OpenAI's playground.

Likely cause: Trailing whitespace in the pasted key. Copy-pasting from some terminals adds a newline or space at the end.

Fix: Settings → API Keys → OpenAI → Edit. Delete the key, re-paste it carefully, save. jekcms auto-trims new entries from 2026-01 forward, but older installs may carry the whitespace.

The login form rejects a password you know is correct

Symptom: The credentials are right, the account is active, but the login screen keeps answering Invalid email or password.

Likely cause: one of two anti-bot measures, and neither of them says so on screen.

The form carries a honeypot field that must stay empty. It is visible to scripts and ignored by humans, so this only bites automated logins - a browser extension that fills every input, or a test script using a generic selector, will fill it and get rejected.

The form also records when it was rendered and rejects submissions made in under two seconds. A password manager that submits instantly can trip this.

Fix: submit the form normally, a moment after it loads. If you are automating a login, target the username and password fields specifically and leave the rest alone.

The licence agreement screen will not let you continue

Symptom: On first login you land on the EULA and the accept button stays greyed out.

Likely cause: it requires three things, not one - you have to scroll the agreement to the end, tick I have read and understood, and tick I accept.

Fix: scroll the agreement box itself to the bottom. It is a separate scroll area from the page, so scrolling the page does not count.

The admin redirects to a domain that does not exist

Symptom: You log in successfully and the browser lands on a site that will not resolve.

Likely cause: the site address entered during setup is not the address you are actually using - a placeholder domain, or https:// on a host still serving http://.

Fix: edit SITE_URL in the .env file in your web root, then log in again. The old session cookie belongs to the old address and will not carry over.