How to create laravel storage symbolic link for production or sub domain system?

How to create laravel storage symbolic link for production or sub domain system?

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

Stefan Bogdanescu

Founder & Senior Architect

Resolving Storage Link Failures in Production Environments

The php artisan storage:link command works predictably during local development because the file system layout is usually straightforward. The application root, the public directory, and the storage folder typically reside in a predictable hierarchy where relative paths resolve as expected. However, transfer this setup to a production server or a sub-domain architecture, and you will likely encounter immediate failure.

When moving a site to production, the most common symptom is discovering that storage appears as a folder instead of a symlink pointing to public/storage. Attempting to recreate this link often triggers permission errors or "file already exists" exceptions if the previous attempt left behind a directory artifact rather than cleaning up correctly. This happens because the command relies on relative path resolution, and what works in your local home directory may not align with the web server's document root or the specific directory structure of a sub-domain deployment.

Understanding the Path Resolution Issue

The core issue lies in how Laravel calculates the symlink destination. The storage:link artisan command creates a symbolic link named public/storage that points to the ./storage/app/public directory relative to the application's root.

In a standard local installation, if your project lives at /home/user/project, the web server (like Apache or Nginx) might serve from /home/user/project/public. The symlink works because both the link target and the source are relative to the same base directory. In production environments, however, you frequently see a split structure:

  1. Application Root: Where your code lives (e.g., /var/www/myapp).
  2. Document Root: Where the web server serves files from (e.g., /var/www/html or a specific sub-domain path).

If your application is cloned into one directory but the web server serves files from another, or if you are deploying to a sub-domain where the document root does not match the application root, the relative path ./storage/app/public resolves incorrectly. The link points to a location that either doesn't exist or points to the wrong file, resulting in 403 Forbidden or 404 Not Found errors when accessing assets.

Cleaning Up Existing Artifacts

Before attempting to create the link again, you must ensure no remnants of previous failed attempts persist. A common mistake is deleting only the symlink but leaving the storage folder inside public. If a directory exists at the target location where a symlink is expected, the command will fail with an error stating it cannot overwrite the existing file or folder.

To resolve this, manually remove the problematic directory if it exists:

rm -rf /path/to/public/storage

Once the destination is clear, you can attempt to run the artisan command again. However, if the path resolution issue remains due to differing application and document roots, the standard command will still fail. In these scenarios, you may need to create the symlink manually or adjust the configuration to point to an absolute path instead of a relative one.

Implementing Absolute Path Symlinks

When relative paths break in production, the robust solution is often to define the storage link using an absolute path. This decouples the symlink creation from the specific directory hierarchy of the web server, ensuring it works regardless of whether the app and public folders are nested or separate.

You can achieve this by creating a custom artisan command or manually constructing the link with full paths. For example, if your application root is /var/www/myapp and you want to link from /var/www/html/public/storage, you would execute:

ln -s /var/www/myapp/storage/app/public /var/www/html/public/storage

This approach guarantees that the web server accesses the correct asset files regardless of how the underlying directories are structured. It also prevents issues where the storage:link command assumes a specific relative depth that differs from your production layout.

Best Practices for Deployment

To avoid these headaches in future deployments, consider modifying your deployment script to handle storage linking explicitly. Instead of relying solely on php artisan storage:link, ensure your CI/CD pipeline checks for the existence of the target directory and removes it before creating the link with the correct path parameters. Additionally, verify file permissions on the production server; the web server user (e.g., www-data) must have read access to the linked files but not write access unless intended by your application logic.

Our network