Troubleshooting Guide

Troubleshooting Guide

Encountering issues with ElmapiCMS? This section covers the most common problems and how to resolve them. If you don’t find your issue here, feel free to reach out via the channels described in the Getting Help & Support page.

Locating & Reading the Logs

ElmapiCMS is built on Laravel, which stores log files in:

storage/logs/laravel.log
  1. Tail the log in real-time 
    cd /path/to/your/project
tail -f storage/logs/laravel.log
  2. Rotate/Clear the log if it grows too large: 
    > storage/logs/laravel.log

Whenever you see a 500 Internal Server Error or a blank page, the first place to look is this log file.

"500 Internal Server Error" / Blank Page

A generic 500 error simply means “something went wrong.” Follow these steps:

  1. Check the log (storage/logs/laravel.log) for the exact exception.
  2. Clear caches – an outdated cache is the #1 culprit: 
    php artisan optimize:clear   # Clears config, route, view, and cache files
php artisan cache:clear      # Clears application cache store
  3. Verify file & folder permissions – the web server must be able to write to storage/ and bootstrap/cache/.
  4. Check your .env values – missing or malformed variables (e.g., DB_*, APP_KEY) will crash the app.
  5. Run database migrations – an out-of-date schema can break pages: 
    php artisan migrate --force

"Vite manifest not found" Error

You may encounter this after deployment when Vite’s build files are missing.

Symptoms: The page throws Vite manifest not found or CSS/JS assets are 404-ing.

Fix:

# Install JS dependencies & build assets
npm install
npm run build          # Production build
 
# OR, for local development
npm run dev            # Hot-reload server

If you are deploying to production, make sure you either:

  1. Commit the public/build/ folder (generated by npm run build), or
  2. Build the assets on the server (CI pipeline, Forge deploy script, etc.).

cPanel Root/Subdomain: Vite Manifest Path Issue

If you deployed ElmapiCMS on a sub-domain via cPanel and now see errors like:

RuntimeException  ›  Vite manifest not found  
Unable to locate file: /home/USER/public_html/build/manifest.json

this almost always means the relative paths were not updated correctly after moving files.

What to check

Re-open the two files you edited in the Subdomain Deployment Guide:

FileLines to ReviewWhat it should point to
index.php (in your sub-domain document root)Around lines 22 and 37../Elmapi3/bootstrap/* (add/remove ../ until the path reaches the Elmapi3 folder)
bootstrap/app.php (inside Elmapi3)The usePublicPath() blockShould reference your sub-domain folder,
e.g. $app->usePublicPath($app->basePath('../public_html/cms.your-domain.com'));

Make sure the relative segments (../) accurately reach the real location of each file on your server. A single wrong ../ is enough to break the manifest lookup.

After fixing the paths

php artisan optimize:clear   # clear config, route & view caches

Refresh the page; the error should disappear once Laravel can read public/build/manifest.json.

"Target class controller does not exist" / Route Issues

After adding, removing, or renaming controllers and routes, you might see errors like Target class [UserController] does not exist.

Steps to resolve:

php artisan route:clear
php artisan route:cache       # (optional) rebuild the route cache

Make sure the file namespace matches the path and the route definition.

Queue Jobs Not Processing

ElmapiCMS dispatches certain tasks (e.g., webhooks, emails) to Laravel’s queue. If jobs are stuck in failed_jobs or not processing:

  1. Start a worker in the background: 
    php artisan queue:work --daemon --tries=3 --backoff=5
  2. For production, use a supervisor (systemd, Supervisor) to keep workers alive.
  3. Monitor the queue with: 
    php artisan queue:failed
php artisan queue:retry <id>

"CSRF Token Mismatch" / API Authentication Errors

If you receive CSRF token mismatch when making requests to the dashboard:

  1. Ensure the domain in SANCTUM_STATEFUL_DOMAINS matches the current hostname.
  2. Clear cookies or try an incognito window to rule out stale tokens.
  3. Verify the session driver (SESSION_DRIVER) and cache driver (CACHE_DRIVER) are properly configured.

Database Connection Failures

A common stack trace in the logs is SQLSTATE[HY000] [2002] Connection refused.

Checklist:

  • DB_HOST – use 127.0.0.1 instead of localhost when using Docker or some MySQL versions.
  • DB_PORT – default MySQL is 3306. Ensure the container/service exposes that port.
  • DB_USERNAME / DB_PASSWORD – verify credentials.
  • Run php artisan migrate to confirm the connection.

Composer Autoload Issues

After downloading new updates, always run:

composer install --prefer-dist --no-dev -o   # For production
composer install                              # For local dev
php artisan optimize:clear

If you see Class not found errors, regenerate the autoloader:

composer dump-autoload

Common Cache Commands

PurposeCommand
Clear & rebuild configuration cachephp artisan config:cache
Clear route cachephp artisan route:clear
Clear compiled viewsphp artisan view:clear
Clear application cache storephp artisan cache:clear
Clear everything in one gophp artisan optimize:clear

Keeping caches fresh avoids many strange, hard-to-trace issues.

Still stuck?

  1. Re-read the logs – many issues show up there first.
  2. Double-check you are running supported versions (see composer.json and package.json).
  3. CodeCanyon: Search item comments for similar reports.
  4. GitHub access: Search Issues and Discussions.
  5. Email [email protected] with steps to reproduce, logs or screenshots, and environment (PHP, database, OS). Include your Envato purchase code or GitHub username, depending on how you bought—see Getting help and support.

We are here to help you get back on track quickly.

PreviousGetting Help & Support

Search documentation

Find guides and reference pages