How to fix Laravel 500 error: Troubleshooting Checklist

Common Failure Symptoms

Laravel 500 errors manifest in several recognizable patterns that help narrow down the problem area before diving into detailed diagnostics.

• Blank white screen with no error message displayed to users
• Generic 'Whoops, something went wrong' message in production mode
• Server responds with HTTP 500 status but application appears partially functional
• Error occurs immediately after deployment, environment change, or server migration
• Specific routes fail while others work correctly
• Error appears intermittently under load or after server restart

Enable Debug Mode and Check Logs

The first diagnostic step is revealing the actual error message hidden behind the generic 500 response. Laravel suppresses detailed errors in production for security, but you need this information to diagnose the problem.

Open your .env file in the application root directory and temporarily set APP_DEBUG=true. Save the file and refresh the failing page. Laravel will now display a detailed error page with the exception message, file location, and stack trace. Capture this information before proceeding.

If the browser still shows a generic error, check the Laravel log file directly at storage/logs/laravel.log. The most recent entries appear at the bottom of the file. Look for entries with the ERROR level that correspond to the timestamp of your failed request.

Important: Always set APP_DEBUG=false before returning to production. Detailed error messages expose sensitive information about your application structure, database schema, and file paths that attackers can exploit.

Verify File Permissions and Ownership

Permission issues are the most frequent cause of Laravel 500 errors, especially after deployment, server migration, or running composer commands under different user accounts. Laravel requires write access to specific directories to function correctly.

The web server user (typically www-data, nginx, or apache) must own the application files and have write permissions on storage and bootstrap/cache directories. Incorrect ownership or restrictive permissions prevent Laravel from writing logs, caching configurations, or storing session data.

Connect to your server via SSH and navigate to your Laravel application root directory. Run these commands to set correct permissions:

sudo chown -R www-data:www-data /path/to/laravel sudo chmod -R 775 storage bootstrap/cache

Replace www-data with your web server user if different. You can identify the correct user by running: ps aux | grep -E 'apache|nginx' | grep -v grep

After setting permissions, clear all caches and test: php artisan cache:clear && php artisan config:clear && php artisan route:clear

Validate Environment Configuration

Environment configuration errors in the .env file are another common trigger for 500 errors. These errors often appear after cloning a repository, deploying to a new server, or rotating credentials.

First, confirm the .env file exists in the application root. If missing, copy .env.example to .env and populate it with your environment-specific values. The APP_KEY value is particularly critical—Laravel uses this key for encryption and session management.

Generate a new application key if missing or suspected corrupt: php artisan key:generate

This command creates a random 32-character key and writes it to your .env file automatically. Never share this key publicly or commit it to version control for production environments.

Verify database connection settings next. Common issues include incorrect DB_HOST values (localhost vs 127.0.0.1), wrong credentials, or database name typos. Test the connection manually: php artisan tinker, then DB::connection()->getPdo();

If the connection fails, double-check DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD in your .env file. Ensure the database exists and the user has appropriate privileges.

After any .env changes, always clear the config cache: php artisan config:clear. Laravel caches configuration for performance, and stale cache is a frequent source of confusion during troubleshooting.

Check PHP and Server Requirements

Laravel has specific PHP version and extension requirements that vary by framework version. Running Laravel on an incompatible PHP version or with missing extensions will trigger 500 errors.

Verify your PHP version matches Laravel requirements. Laravel 11 requires PHP 8.2 or higher, Laravel 10 requires PHP 8.1 or higher, and Laravel 9 requires PHP 8.0 or higher. Check your version: php -v

If your PHP version is incompatible, you'll need to upgrade PHP on your server or configure your web server to use a different PHP version if multiple versions are installed.

Verify required PHP extensions are installed and enabled: php -m | grep -E 'openssl|pdo|mbstring|tokenizer|xml|ctype|json|bcmath'

Missing extensions must be installed through your package manager. For Ubuntu/Debian: sudo apt install php-mbstring php-xml php-bcmath. For CentOS/RHEL: sudo yum install php-mbstring php-xml php-bcmath.

Check PHP memory_limit in php.ini. Laravel applications, especially during composer operations or heavy processing, may require more than the default 128M. Increase to at least 256M for production applications. Locate your php.ini file: php --ini, then edit the memory_limit directive.

After changing PHP configuration, restart your web server: sudo systemctl restart apache2 (or nginx or php-fpm depending on your setup).

Clear Application Caches

Stale or corrupted cache files frequently cause 500 errors after deployments, configuration changes, or code updates. Laravel caches configuration, routes, views, and application data for performance, but these caches can become out of sync with code changes.

Run this comprehensive cache clearing sequence: php artisan cache:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear

These commands clear the application cache, configuration cache, route cache, and compiled view templates respectively. Run all four commands after any deployment or configuration change.

If Opcache is enabled (common in production environments), you may also need to restart PHP-FPM to clear the opcache: sudo systemctl restart php-fpm (or php8.2-fpm depending on your PHP version).

For persistent issues after clearing caches, manually delete the cache directories: rm -rf storage/framework/cache/data/* and rm -rf storage/framework/views/*. Laravel will recreate these automatically on the next request.

After clearing caches, rebuild optimized versions for production: php artisan config:cache && php artisan route:cache. Never cache configuration in development environments where APP_DEBUG=true, as it can make debugging more difficult.

Investigate Database and Migration Issues

Database connectivity problems and failed migrations are common sources of 500 errors, particularly for applications that run database queries during the bootstrap process or use database-backed sessions.

Test basic database connectivity first: php artisan migrate:status. This command attempts to connect to the database and display migration status. Connection failures will produce clear error messages about credentials, hostname, or network issues.

If migrations are pending, running them may resolve the issue: php artisan migrate. However, back up your database before running migrations on production systems, as migrations can alter or delete data irreversibly.

Check for migration files that reference deleted model classes or use invalid syntax. These will cause 500 errors when Laravel attempts to process them. Review recent migration files in database/migrations/ for errors.

If using database sessions (SESSION_DRIVER=database in .env), verify the sessions table exists: php artisan session:table followed by php artisan migrate. Missing session tables prevent Laravel from storing session data, triggering 500 errors on authenticated routes.

For queue or cache issues using database drivers, verify the respective tables exist: php artisan queue:table, php artisan cache:table, then php artisan migrate.

Review Web Server Configuration

Web server misconfiguration can cause 500 errors that appear to originate from Laravel but actually stem from Apache or Nginx settings.

For Apache servers, verify the .htaccess file exists in the public directory and mod_rewrite is enabled. The .htaccess file handles URL rewriting essential for Laravel routing. Enable mod_rewrite if disabled: sudo a2enmod rewrite && sudo systemctl restart apache2

Ensure the Apache virtual host allows .htaccess overrides by including AllowOverride All in the directory configuration block. Without this directive, Apache ignores .htaccess files.

For Nginx servers, verify the server block configuration includes proper FastCGI parameter passing and try_files directive. A typical Laravel Nginx configuration includes: try_files $uri $uri/ /index.php?$query_string;

Check web server error logs separately from Laravel logs. Apache logs typically reside in /var/log/apache2/ and Nginx logs in /var/log/nginx/. These logs may reveal permission issues, PHP execution failures, or resource limits that Laravel cannot detect.

Verify the document root points to the public directory, not the application root. Laravel applications must serve from the public directory to function correctly and maintain security boundaries.