Troubleshooting

Blank White Page

A blank page usually means a PHP fatal error with display_errors turned off.

  • Temporarily set DEBUG to true in config/conf.php to see the error
  • Check your server's PHP error log (usually at /var/log/php_errors.log or in cPanel → Error Logs)
  • Verify your PHP version is 8.4+ — older versions will be fatal on PHP 8.4 syntax

404 on Every Page (except home)

URL rewriting is not working. Common causes:

  • Apache: mod_rewrite is not enabled — ask your host to enable it, or add AllowOverride All to your VirtualHost
  • Apache: the .htaccess file was not uploaded (it is hidden — enable "show hidden files" in your FTP client)
  • Nginx: try_files $uri $uri/ /index.php?$args; must be in the server block

Database Connection Failed

  • Verify credentials in config/conf.php match those in your hosting control panel
  • The database user must have privileges on the named database — not just on *.*
  • Some hosts require the database host to be an IP or socket path instead of localhost

File Uploads Failing

  • The uploads/ directory must exist and be writable (chmod 755 or 775)
  • Check upload_max_filesize and post_max_size in your PHP ini
  • Ensure the GD extension is loaded for image processing

Email Receiving and Sending

If you are not able to send and receive emails, this is most likely due to your server configuration. Most hosting companies disable the PHP mail function, so your other choice is SMTP, or Sendmail. Wojo Framework supports both of those. First, enable the debug console and find the exact error message related to sending email.

To switch to SMTP or sendmail, go to /admin/configuration/ page and select either SMTP or sendmail option.

Some hosting companies require that the email address "from" is from your own domain, and therefore, you must use your own hosting SMTP settings. If you are using SMTP, make sure to configure the SMTP settings correctly, including the SMTP server, port, username, and password.

CSS / JS Not Loading

  • Confirm site_dir in database settings table matches your installation directory
  • Open the browser's Network tab to see which URL is being requested for the missing asset
  • If installed in a subfolder, make sure site_dir includes the subfolder path

Session / Login Issues

  • Ensure the PHP session save path is writable on your server
  • Mixed HTTP/HTTPS can invalidate session cookies — use HTTPS consistently
  • If running multiple apps on the same domain, each must have a unique INSTALL_KEY to avoid session collisions