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.

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.