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
publicdisk. -
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:
-
Where Laravel's
public_path()points. -
Where the symbolic link was created.
-
Where the uploaded files are stored.
-
Whether the hosting provider allows symbolic links.
-
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
locationblocks. -
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:
-
Use the
publicdisk consistently for files intended for direct browser access. -
Generate URLs through Laravel filesystem helpers.
-
Confirm the actual production document root.
-
Preserve uploaded files using suitable persistent storage.
-
Include storage-link verification in deployment checks.
-
Keep private uploads outside publicly exposed directories.
-
Avoid unsafe permission changes.
-
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