When you have a code bug in a Laravel application, you can typically find more information about the problem via the error page Laravel shows or via your Laravel error log files.
Occasionally, though, you might have a system-level bug that prevents the application from even loading. As a result, Laravel is not able to output the error behind the problem and you might see a 500 server error in the browser with little to no helpful information in your error log files.
These system-level bugs typically occur when first setting up a Laravel application, either as a brand new install, or when deploying an existing Laravel application on a new server.
In this guide, I will go over five common system-level bugs, outlining their symptoms and how to fix them.
Issue 1 - Missing .env file
Every Laravel application needs to have a .env file in the root of the application that contains essential environment-level configurations. Without it, your Laravel application will not be able to boot up and you will see a Laravel 500 SERVER ERROR page.
You will also see the error "No application encryption key has been specified." in your Laravel error log because the application will be looking for an encryption key that should exist in the .env file.
To resolve this problem, you can create a .env file using a copy of an environment file you might have already set up on another server that was already running your application. If you don’t have an existing .env file to work from, you can create one by duplicating the provided .env.example file that comes with every Laravel application:
> cp .env.example .env
After doing this, run the following command to have Laravel generate an encryption key which it will write to your .env file:
> php artisan key:generate
Finally, edit the .env file making any changes necessary to match the needs of your application.
When you install a fresh Laravel application, the .env file is created for you. But if you clone an existing Laravel application to a new server/system, the .env file will need to be manually created as it is commonly excluded from version control repositories.
Issue 2 - Missing APP_KEY in .env file
Related to the above issue, if you load your application and you see the error No application encryption key has been specified. this means you have a .env file but the value for APP_KEY is missing.
To fix this, simply have Laravel generate a key for you with the following Artisan command:
> php artisan key:generate
Issue 3 - Bug in .env file
Another issue related to your .env file is there might be a bug within the file itself. For example, you can’t have multi-word values with spaces without surrounding the value in quotes.
A bug like this will produce a generic HTTP ERROR 500 page when you attempt to load your application:
If you’re unsure if you have an error in your .env file, try invoking Artisan (php artisan) as it will often report back on problems:
Issue 4 - Incorrect permissions
When your Laravel application runs it needs to be able to write files to the directories storage and bootstrap/cache. If the permissions on these directories are set such that this is not possible, you may see an error like the following:
To fix this, you need to change the owner of the storage and bootstrap/cache directories to the same user that your web server is running under.
To find out which user this is, run the following command to locate your web process (commonly either Apache/httpd or Nginx) and identify its owner:
> ps aux | egrep '(apache|httpd|nginx)'
Here is example output showing three processes, which I’ve labeled 1, 2, and 3:
For each process, note that the left most value is the process owner (in this case, that’s root, www-data, and root).
Process 1 is tied to our web server, but it's the root (Admin) user, and we don’t want to grant admin access to our writable directories. Given that, we’ll focus on Process 2 where we see the owner is www-data. You can ignore Process 3 because that’s simply showing the process for the search command you just ran.
Once you know which user your web server is acting under (in our example that’s www-data) we want to make this user the owner of our Laravel storage and bootstrap/cache directories with the following chown commands:
> chown -R www-data storage
> chown -R www-data bootstrap/cache
Issue 5 - Missing vendor directory
If you see an error about a missing vendor/autoload.php file, this likely means you‘re missing Composer’s vendor directory that should contain all your outside dependencies:
This commonly happens when you set up an existing Laravel application on a new server and forget to invoke Composer to build the vendor directory.
To fix this on a development server, run the following command:
> composer update
To fix this on a production server, run the following command:
> composer install --no-dev