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.).

Shared hosting: Vite manifest not found

If you see an error like this after a shared hosting install:

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

Laravel cannot find public/build/manifest.json.

What to check

1. Make sure that you moved all files from the package public/ folder into the document root. The build/ folder must be there.
2. Make sure that you completed the web installer. The installer sets the public path for domain and subdomain layouts.
3. If you still see the error, open elmapicms/bootstrap/app.php and make sure that usePublicPath() points to your real document root.

After you correct the paths

If your host gives SSH or a terminal:

cd elmapicms
php artisan optimize:clear

Then refresh the page.

"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.

API Rate Limit (429) During Frontend Template Builds

Frontend template builds (and other local scripts) can send many API requests in a short window and hit ElmapiCMS’s default API rate limit (300 requests per minute). When that happens, the API responds with 429 Too Many Requests and the build may fail or stall.

Fix (local / development): raise the limit in .env:

API_RATE_LIMIT_PER_MINUTE=2000

Then clear caches:

php artisan optimize:clear

Keep production at a sensible value (the default 300 is usually fine). Authentication endpoints have their own separate rate limits. See .env Configuration and API Rate Limiting.

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

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.