Laravel storage link won't work on production

Laravel storage link won't work on production

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Why storage:link Fails on Production and How to Fix It

You are likely encountering a classic deployment misconfiguration where the symbolic link created by php artisan storage:link appears correct in your local environment but vanishes or behaves differently on your live server. The core issue isn't necessarily that the link command failed; it's often that the underlying filesystem permissions and directory structure don't align with how PHP runs on a production server versus your local machine.

When you run php artisan storage:link, Laravel creates a symbolic link from public/storage to storage/app/public. On a standard local setup, this is straightforward because your web server (like Apache or Nginx) and your PHP CLI process usually run under the same user identity (e.g., www-data or laravel). However, production environments frequently separate these identities.

The Permission Mismatch

The most common reason images appear in storage/app/public but not in your public_html root is that the web server cannot see the linked files due to permission restrictions. If your PHP process uploads an image successfully, it means the writable directory permissions are correct for the CLI process. But if the web server user (e.g., www-data) does not own the storage directory or lacks execute permissions on the path, the link becomes inaccessible via HTTP requests.

To diagnose this, check the ownership of your storage directories:

ls -la /path/to/your/project/storage/app/public/images

If the files are owned by your local user (e.g., vagrant or yourusername) but the web server runs as www-data, the server cannot access them. You must ensure the web server user owns the storage and bootstrap/cache directories:

sudo chown -R www-data:www-data storage bootstrap/cache

After updating permissions, verify that the symbolic link exists in the public folder:

ls -la /path/to/your/project/public/storage

If the link is missing entirely, re-run the artisan command with elevated privileges if necessary:

sudo php artisan storage:link

Reviewing Filesystem Configuration

Your configuration files play a critical role in determining where files are stored and how they are served. In your .env file, you have set FILESYSTEM_DRIVER=public. This defaults to the local driver, which is correct for serving static assets. However, ensure that the APP_URL environment variable is correctly set to your production domain. If APP_URL points to a local address like http://localhost, browsers may encounter security restrictions (Mixed Content) or incorrect redirect paths when trying to access the /storage route.

In your config/filesystems.php, the public disk configuration looks standard:

'public' => [
    'driver' => 'local',
    'root' => storage_path('app/public'),
    'url' => env('APP_URL').'/storage',
    'visibility' => 'public',
],

This configuration is sound, provided that APP_URL reflects your actual production domain. The visibility setting being 'public' ensures that the public/ prefix is not added to URLs, which is the desired behavior for a linked storage folder.

Understanding Image Processing Constraints

Your controller logic handles image resizing and saving before assigning the filename to the database record. This approach works locally because PHP's GD or Imagick extensions can process images directly from disk. On some production setups, especially those using containerized environments like Docker or managed hosting (e.g., Heroku, AWS Lambda), file system operations might be restricted or behave differently due to read-only layers or ephemeral storage.

Ensure that the storage/app/public directory is mounted as writable in your web server configuration. If you are using a reverse proxy or load balancer, verify that the backend server has write access to the storage path. Additionally, check that your PHP extensions for image manipulation (GD or Imagick) are enabled in your production environment:

php -m | grep -E "gd|imagick"

If these extensions are missing, resizing operations will fail silently or throw exceptions depending on your error reporting level.

When to Use the S3 Driver

While fixing local storage links is often sufficient for traditional LAMP/LEMP stacks, consider switching to an external object storage driver like AWS S3 if you face persistent permission issues or need better scalability. The S3 driver handles visibility and caching automatically, reducing the risk of misconfigured symbolic links. However, this requires setting up credentials and updating your config/filesystems.php accordingly.

For most standard deployments, ensuring correct ownership (www-data) and a valid APP_URL resolves the issue. Always test file uploads in production with verbose error logging enabled temporarily to catch any silent failures caused by permission denials or missing extensions.

Our network