Fix Laravel Stale Environment Changes After Deployment

If your Laravel environment changes (like new values in your .env file) don’t take effect after deployment, the fix is almost always to clear and rebuild the configuration cache. Run php artisan config:clear followed by php artisan config:cache on your server, and if you use a process manager like Supervisor, restart your queue workers and PHP-FPM.

Why Laravel Caches Environment Variables

Laravel’s configuration system is designed for speed. When you run php artisan config:cache, the framework compiles all your configuration files (which read from the .env file) into a single PHP array stored in bootstrap/cache/config.php. On every request, Laravel loads this cached file instead of parsing the .env file and all config files individually. This dramatically reduces disk I/O and speeds up your application.

However, this caching means that once you change a value in .env, Laravel continues to use the old cached configuration until you explicitly clear it. If you deploy new code that reads a new environment variable, but the cache still holds the old values, your application will behave as if the change never happened. This is the most common cause of “stale” environment changes after deployment.

How to Fix Stale Environment Changes

Here are the exact steps to force Laravel to pick up your new environment values:

1. Clear the configuration cache: Run php artisan config:clear on your server. This deletes the bootstrap/cache/config.php file.
2. Rebuild the cache (optional but recommended): Run php artisan config:cache to rebuild the cache with the new values. This step is optional in development but highly recommended in production for performance.
3. Restart your queue workers: If you use queues (e.g., for emails, jobs), long-running queue workers may hold the old config in memory. Restart them with php artisan queue:restart or via your process manager (e.g., supervisorctl restart all).
4. Restart PHP-FPM: If you use PHP-FPM with opcache, the cached config might be served from opcache. Restart PHP-FPM with sudo systemctl restart php8.1-fpm (adjust the version) to clear opcache.
5. Clear other caches: Run php artisan cache:clear and php artisan view:clear if you suspect other caches are involved, though they are less likely to cause stale environment issues.

Common Causes of Stale Environment Variables

Beyond the config cache, other factors can keep old environment values alive:

• Opcache: PHP’s opcache can cache the compiled config file. If you don’t restart PHP-FPM, the old config may be served from opcache even after clearing the Laravel cache.
• Queue workers: Long-running queue workers (like those managed by Supervisor) load the config once at startup. They won’t see changes until restarted.
• Horizon: If you use Laravel Horizon for queues, it also caches config. Restart Horizon with php artisan horizon:terminate.
• Envoy or deploy scripts: Some deployment tools run config:cache automatically. If your deploy script runs it after copying files, but you manually change .env later, the cache will be stale.
• Shared hosting: On shared hosting, you may not have CLI access. In that case, you can create a temporary route or use a one-off script to run Artisan::call('config:clear').

How to Prevent Stale Environment Issues

Prevention is better than cure. Here are best practices to avoid this problem:

• Always run config:cache after changing .env in production. Make it part of your deployment script.
• Use environment-specific .env files. For example, .env.production and .env.staging. Copy the appropriate one to .env during deployment, then cache.
• Restart queue workers and PHP-FPM in your deploy script. This ensures all long-running processes pick up the new config.
• Consider using a config repository. Tools like Laravel Envoy or Forge can automate these steps.
• In development, never run config:cache unless you’re testing the production behavior. It can confuse you when changes don’t appear.

What If Clearing the Cache Doesn’t Work?

If you’ve cleared the config cache and restarted everything, but the changes still don’t take effect, check the following:

• Verify the file path: Ensure you’re editing the correct .env file. On some setups, the .env file might be outside the project root (e.g., in a parent directory).
• Check for syntax errors: A typo in .env (like a missing equals sign) can cause Laravel to silently fall back to default values. Run php artisan config:cache and see if it reports an error.
• Look for hardcoded values: If your code uses env() directly outside of config files, those calls are not cached and will always read from .env. But if you use config() with a cached config, the value comes from the cache. Ensure you’re not mixing both.
• Check for opcache revalidation: If opcache is set to opcache.validate_timestamps=0, it will never check for file changes. Restart PHP-FPM or change the setting.

Config Caching vs. Env() Helper

A common misconception is that env() calls outside config files are affected by config:cache. In fact, when you run config:cache, Laravel replaces all env() calls in your config files with the actual values, and those values are stored in the cache. However, if you call env() directly in your application code (e.g., in a controller), it will read from the .env file at runtime, ignoring the cache. This can lead to inconsistent behavior. The recommended practice is to always use config() helper, and define the environment variable in a config file. That way, caching works as expected.

Deployment Script Example

Here is a typical sequence of commands you might run during deployment to avoid stale environment issues:

# After pulling new code and updating .env
php artisan config:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart
sudo systemctl restart php8.1-fpm  # adjust version

If you use Supervisor for queue workers, replace queue:restart with supervisorctl restart all. Some teams also run php artisan migrate --force here, but that’s separate from environment caching.

Frequently Asked Questions

Why does my .env change not show up even after config:clear?

If you’ve cleared the config cache but still see old values, check if PHP-FPM or opcache is serving a cached version of the config file. Restart PHP-FPM to clear opcache. Also, ensure you’re editing the correct .env file—sometimes there are multiple copies (e.g., .env.example vs .env).

Do I need to run config:cache in production?

It’s recommended for performance, but not strictly required. If you skip it, Laravel will parse .env and all config files on every request, which is slower. If you do run it, remember to clear it after any .env change.

How do I clear config cache without SSH access?

You can create a temporary route in your web application that calls Artisan::call('config:clear'), then hit that URL. Remove the route immediately after. Alternatively, some hosting panels (like cPanel) offer a “Run Artisan” feature.

Why does my queue worker not see the new env values?

Queue workers are long-running processes. They load the config once at startup and keep it in memory. You must restart them after changing .env. Use php artisan queue:restart or restart via Supervisor.

Can I use env() directly in my code after config:cache?

Yes, but it’s not recommended. env() calls outside config files are not cached and will read from .env at runtime. This can lead to inconsistencies if you expect caching. Use config() instead.

What is the difference between config:clear and cache:clear?

config:clear removes the configuration cache file (bootstrap/cache/config.php). cache:clear clears the application cache (like cached data from Cache::put()). They are independent; you may need both depending on the situation.

Related

• Drone Simulators vs Indoor Whoops vs Gimbals
• Word Show Hide Paste Options: How to Turn It Off
• Jubilee Abilities in Marvel Rivals: Kit, Ultimate & Team-Ups