Skip to main content
← Back to articles
Debugging note • Laravel production issue and solution

Laravel Storage Link Not Working: The Complete Fix Guide For Public Files In 2026

Birendra Jung Rai • 15 min read

Production debugging note

This article explains the real cause of the issue, the correct fix, and the checks that help prevent the same problem from returning.

Your Laravel application uploads a file successfully, but the image won't display. The browser returns a 404 error, or the file works locally but disappears after deployment.

If your Laravel storage link is not working, the problem is usually related to a missing symbolic link, an incorrect file path, filesystem permissions, or the disk configuration.

I've encountered storage-related problems while working with Laravel applications, particularly when moving between local development and production environments. The most effective approach is to verify each part of the file-storage process instead of repeatedly running commands without understanding the cause.

This guide explains how to diagnose and fix Laravel storage problems, including common issues with Docker, Apache, Nginx, and cPanel hosting.

Quick Fix: Check Your Laravel Storage Link

If you are using Laravel's standard public disk, start from the application root directory.

Run:

php artisan storage:link

This creates the symbolic link Laravel normally needs to expose publicly accessible files.

The expected directory relationship is:

your-laravel-project/
├── public/
│   └── storage -> ../storage/app/public
└── storage/
    └── app/
        └── public/
            └── images/
                └── photo.jpg

The file can then be accessed through a URL such as:

https://example.com/storage/images/photo.jpg

Important: Running storage:link only solves the problem if the file is stored on the correct disk and the web server can access it.

If the command succeeds but your images still return 404 or 403 errors, continue with the checks below.

1. Understand How Laravel Public Storage Works

Laravel separates application storage from files that should be accessible through the browser.

For the standard local public disk, uploaded files are stored inside:

storage/app/public

However, the web server normally serves public assets from:

public/

Laravel connects these directories using a symbolic link:

public/storage
    ↓
storage/app/public

The following command creates this connection:

php artisan storage:link

A symbolic link is essentially a filesystem reference pointing to another location.

It allows the web server to access files stored outside the public directory without physically copying every uploaded file.

Public storage versus private storage

Not every uploaded file should be publicly accessible.

For example:

  • Product images and public profile pictures may belong on the public disk.

  • Invoices, private documents, and sensitive user uploads should generally remain on a protected disk.

Creating a storage link does not mean every file inside Laravel's storage directory becomes publicly accessible.

Only the configured linked locations are exposed.

This distinction is important for both functionality and security.

2. Identify Why the Storage Link Is Not Working

Before modifying anything, identify the actual cause.

Symptom Possible cause What to inspect
Uploaded image returns 404 Missing storage link public/storage
Symlink exists but files return 404 Incorrect target or file path Symlink target and disk root
File returns 403 Permissions or web-server restrictions Ownership and server logs
Files work locally but fail in production Different deployment structure Production document root
Upload succeeds but image URL is incorrect Wrong filesystem disk or URL config/filesystems.php
Files disappear after container recreation Missing persistent volume Docker volume configuration
URLs use the wrong domain or protocol Incorrect application URL configuration APP_URL and proxy settings

The HTTP status can help narrow down the problem, but it does not identify the root cause by itself.

Let's investigate the most common scenarios.

3. Check Whether the Symbolic Link Exists

Start in your Laravel application's root directory.

Run:

ls -ld public/storage

A typical symbolic link may appear as:

public/storage -> ../storage/app/public

The exact displayed target can vary depending on how the link was created.

If the path does not exist, create the link:

php artisan storage:link

If Laravel reports that the link already exists, don't immediately delete it.

First determine what the path actually contains.

Run:

test -L public/storage && echo "Symbolic link exists"

Then inspect its target:

readlink public/storage

You can also check the resolved location:

readlink -f public/storage

For a standard Laravel installation, the resolved target should correspond to the application's storage/app/public directory.

What if public/storage is a real directory?

This requires additional care.

A real directory is not the same as a symbolic link.

Before deleting or replacing anything, run:

ls -ld public/storage

If it is an actual directory, investigate its contents and determine whether your application stores files there.

Never blindly delete public/storage on a production system. It may contain real uploaded data or be a mounted directory.

If you confirm that the path is an incorrect symbolic link, remove only that link after verifying its target and ensuring it is safe to do so.

For a verified symbolic link:

unlink public/storage

Then recreate it:

php artisan storage:link

Do not use this sequence unless you have confirmed that public/storage is a symlink and understand its role in the deployment.

4. Verify That the Uploaded File Actually Exists

A working symbolic link cannot serve a file that was saved to the wrong directory.

Suppose your application generates this URL:

https://example.com/storage/images/photo.jpg

For the standard public disk, the corresponding file should exist at:

storage/app/public/images/photo.jpg

Check it:

ls -l storage/app/public/images/photo.jpg

If the file is missing, investigate the upload process.

For example, consider this Laravel upload code:

$path = $request->file('photo')->store('images', 'public');

The uploaded file is stored on the public disk.

The returned path may look like:

images/generated-filename.jpg

You can then generate its public URL:

use Illuminate\Support\Facades\Storage;

$url = Storage::disk('public')->url($path);

This keeps the upload location and URL generation consistent.

A common mistake

Consider this code:

$path = $request->file('photo')->store('images', 'local');

The file is stored on the local disk, not the public disk.

In a standard modern Laravel configuration, the local disk may point to:

storage/app/private

Older applications may use a different configured root.

Either way, files stored on the local disk are not automatically exposed through public/storage.

Running php artisan storage:link will not fix a mismatch between the storage disk and the URL.

The solution is to use the correct disk for files intended for public access, not to expose private storage directories.

5. Check Laravel's Filesystem Configuration

Open:

config/filesystems.php

Look for the public disk configuration.

A typical configuration resembles:

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

The important settings are:

Driver

'driver' => 'local'

The files are stored on the server's filesystem.

Root

'root' => storage_path('app/public')

This identifies where the public disk stores its files.

URL

'url' => env('APP_URL').'/storage'

This determines the base URL used when generating public file links.

Visibility

'visibility' => 'public'

This indicates that files on the disk are intended for public access.

Your application may have additional settings or customized disks. Review the existing configuration before changing it.

Verify APP_URL

In your .env file, check:

APP_URL=https://example.com

Replace the example domain with your actual application domain.

An incorrect APP_URL can lead to generated links using the wrong domain or protocol.

However, changing APP_URL does not repair a missing file, broken symlink, or inaccessible directory.

It only addresses URL-generation problems where that configuration is relevant.

6. Check Filesystem Permissions and Ownership

On Linux servers, the web-server process needs appropriate permissions to access public files.

Directories generally require traversal permission, while files require read permission.

Start by inspecting the current permissions:

ls -ld storage
ls -ld storage/app
ls -ld storage/app/public
ls -ld public/storage

Then inspect an affected file:

ls -l storage/app/public/images/photo.jpg

Pay attention to:

  • File ownership.

  • Directory ownership.

  • Read permissions.

  • Directory traversal permissions.

  • The user running the web server or PHP process.

You may see recommendations to use permission modes such as 775 for directories or 664 for files.

These are examples, not universal requirements.

The correct configuration depends on your server users, groups, deployment method, and security model.

Avoid using chmod -R 777 as a troubleshooting shortcut.

It can create unnecessary security exposure and does not solve ownership or path-configuration problems.

If the permissions appear incorrect, identify the actual web-server user and deployment ownership before applying changes.

7. Laravel Storage Link Not Working on Docker

Docker introduces another possible source of confusion: the container filesystem may differ from the host filesystem.

For example, your application might create a symbolic link inside a container, but the target directory may not exist there or may be replaced by a mounted volume.

Step 1: Enter the Laravel container

If your Docker Compose service is named app, run:

docker compose exec app sh

Step 2: Inspect the link inside the container

Run:

ls -ld public/storage
readlink -f public/storage

Step 3: Check the target file

For example:

ls -l storage/app/public/images/photo.jpg

Step 4: Create the link if necessary

If the link is genuinely missing:

php artisan storage:link

Step 5: Verify the volume configuration

Review your docker-compose.yml or Compose configuration.

If uploaded files exist only inside a temporary container filesystem, they may disappear when that container is recreated.

Use appropriate persistent storage for application uploads.

Also ensure that the web-server container can access the files if Nginx or Apache runs separately from PHP.

Important: A symbolic link created on the host may not resolve correctly inside a container if its target points to a host-only filesystem path.

Always inspect the path from the environment that actually serves the request.

8. Laravel Storage Link Not Working on cPanel

Shared hosting creates another common situation.

Your Laravel application may be located outside public_html, while the web server serves files from public_html.

For example:

/home/account/laravel-app/

and:

/home/account/public_html/

In this configuration, Laravel's default public_path() may not correspond to the actual document root unless the application has been configured accordingly.

Running:

php artisan storage:link

might create a perfectly valid link inside the Laravel project's public directory while the web server is serving a different directory.

What to check

First, identify the actual document root configured in cPanel.

Then verify:

  1. Where Laravel's public_path() points.

  2. Where the symbolic link was created.

  3. Where the uploaded files are stored.

  4. Whether the hosting provider allows symbolic links.

  5. Whether Apache can follow the link.

The solution depends on the deployment structure.

For a properly configured Laravel deployment, the preferred approach is to make the web-server document root point to the intended public directory.

If your hosting arrangement uses a customized public directory, the application and filesystem configuration must agree with that structure.

Avoid copying private Laravel application files into publicly accessible locations simply to make uploads work.

What if cPanel blocks symbolic links?

Some hosting environments restrict symbolic links or access through them.

In that case, verify the restriction with the hosting provider.

A supported alternative may involve serving files through authorized Laravel routes or using an appropriate object-storage service.

Do not bypass hosting security restrictions with broad filesystem permissions.

9. Check Apache or Nginx Configuration

Sometimes the symbolic link and the stored file are correct, but the web server still refuses to serve them.

Apache

Check:

  • Whether the document root is correct.

  • Whether the server permits access to the linked target.

  • Whether applicable symlink restrictions are enabled.

  • Whether access rules block the requested path.

  • Whether the server logs contain relevant errors.

A 403 response may indicate an access restriction, but the exact cause should be confirmed through server configuration and logs.

Nginx

Nginx configurations may restrict symbolic link access or prevent certain file paths from being served.

Check the effective server configuration, including:

  • The document root.

  • Relevant location blocks.

  • File-access restrictions.

  • Symbolic link policies.

  • Error logs.

Do not disable security protections globally just to make one storage URL work.

Fix the specific configuration problem after identifying it.

10. Clear Configuration Cache Only When Necessary

Laravel can cache configuration settings for performance.

If you modify .env or config/filesystems.php, an existing configuration cache may continue using previous values.

Check whether your application has cached configuration.

If a refresh is required, you can use:

php artisan config:clear

Once the correct configuration is verified, rebuild the cache:

php artisan config:cache

Perform these operations as part of an approved deployment procedure when working in production.

Avoid treating the following command as a universal fix:

php artisan cache:clear

It clears application cache data rather than specifically correcting a symbolic link.

Likewise, broad cache-clearing commands may affect other application behaviour without fixing the underlying storage problem.

If a physical symlink is missing, clearing Laravel's cache will not create it.

11. Verify That the Storage Problem Is Fixed

After applying the appropriate correction, verify the complete process.

Step 1: Confirm the symbolic link

ls -ld public/storage

Step 2: Confirm the file exists

ls -l storage/app/public/images/photo.jpg

Step 3: Verify the generated URL

In Laravel, generate the URL using the configured public disk:

Storage::disk('public')->url('images/photo.jpg');

Step 4: Test the URL

Use your browser or run:

curl -sS -o /dev/null -w '%{http_code}\n' \
'https://example.com/storage/images/photo.jpg'

For a publicly accessible file, you generally expect:

200

Step 5: Test an actual upload

Upload a new, non-sensitive test image through the application's normal upload workflow.

Verify that:

  • The upload succeeds.

  • The file is stored on the intended disk.

  • The generated URL is correct.

  • The image loads in the browser.

  • The file remains available after the relevant deployment or container restart.

This final test is important because an existing image loading correctly does not necessarily prove the current upload process is configured correctly.

12. How to Prevent Storage Link Problems During Deployment

Prevention is mostly about making the storage workflow predictable.

I recommend the following practices:

  1. Use the public disk consistently for files intended for direct browser access.

  2. Generate URLs through Laravel filesystem helpers.

  3. Confirm the actual production document root.

  4. Preserve uploaded files using suitable persistent storage.

  5. Include storage-link verification in deployment checks.

  6. Keep private uploads outside publicly exposed directories.

  7. Avoid unsafe permission changes.

  8. Test file upload and retrieval after relevant deployment changes.

Where appropriate, php artisan storage:link can be included in a deployment process.

However, an automated deployment should not silently replace an existing directory or symlink without verifying what it contains.

The goal is not simply to run more commands during deployment. It is to make the process safe, predictable, and repeatable.

Conclusion

When a Laravel storage link is not working, the most reliable solution is to identify where the connection between the stored file and the public URL breaks.

Start with the symbolic link. Then verify the actual file location, filesystem disk, permissions, and web-server configuration.

For Docker and cPanel deployments, also confirm that Laravel's configured public directory matches the filesystem environment serving the request.

Most importantly, don't delete directories, change permissions, or clear caches without first identifying the cause.

A short, systematic investigation is usually more useful than repeatedly trying generic fixes.

Frequently Asked Questions

Why does Laravel return a 404 error for uploaded images?

A 404 may occur because the storage link is missing, the linked directory is incorrect, the uploaded file does not exist at the expected path, or the generated URL does not match the configured disk.

Verify the file path and symbolic link before modifying application code.

How do I check whether Laravel's storage link exists?

From your application's root directory, run:

ls -ld public/storage

To inspect the symbolic link's target:

readlink public/storage

Use readlink -f public/storage on supported Linux systems to inspect the resolved destination.

What if php artisan storage:link says the link already exists?

Inspect public/storage before making changes.

Determine whether it is a valid symbolic link, a broken symbolic link, or a real directory.

Only replace the path after confirming what it contains and whether doing so is safe.

Why does Laravel storage work locally but not on cPanel?

The production document root may differ from Laravel's configured public directory. Hosting-level permissions or symbolic link restrictions can also prevent file access.

Inspect the actual hosting paths and server configuration.

Why are uploaded files inaccessible even though the storage link works?

The file may have been saved to another disk, such as local, while the application generates a URL assuming the public disk.

Check the disk used during upload and the method used to generate its URL.

Should I use chmod 777 to fix Laravel storage permissions?

No. Broad permissions are not an appropriate general solution.

Identify the web-server user, ownership, directory traversal permissions, and actual access restrictions before making permission changes.

Do I need to clear Laravel's cache after creating the storage link?

Normally, creating a filesystem symlink does not require clearing Laravel's application cache.

Configuration cache refreshes are relevant when cached filesystem settings have changed.

Can I use Laravel storage without symbolic links?

Yes.

Depending on your requirements, you can serve authorized files through Laravel routes or use storage services such as Amazon S3.

The appropriate approach depends on whether the files are public, private, local, or remotely stored.


Official References

Laravel Documentation — File Storage
https://laravel.com/docs/12.x/filesystem

Laravel Documentation — Directory Structure
https://laravel.com/docs/12.x/structure

Laravel Documentation — Deployment
https://laravel.com/docs/12.x/deployment

Need help with a similar issue?

Let’s make the next technical decision clearer.

Share the problem, the relevant error, or the current system. I can help identify the practical next step.

Request a project review

Continue reading

Related Laravel fixes

View all articles →
Birendra Jung Rai

Birendra Jung Rai

Laravel Engineer • System Architect • Technical Educator