Uploaded images return 404 after deploying a Laravel app
404 Not Found for /storage/avatars/photo.jpgShort answer
Files in storage/app/public are only reachable from the web through a symbolic link at public/storage. A fresh server or a new release folder does not have that link until you run php artisan storage:link. If the link exists, check the disk the file was saved to and the url of the public disk.
Fix it fast
1Find out which cause you have
Look at what public/storage is on the server. It should be a symlink that points at storage/app/public.
ls -ld public/storage ls storage/app/public | head2Match what you see, then jump to its fix
- 1
ls: cannot access 'public/storage': No such file or directoryThe symbolic link was never created on this serverFix - 2
The file exists under storage/app/private (or storage/app), and nothing is in storage/app/public.The file was written to the private local disk, not the public oneFix - 3
The file opens when you type the correct address by hand, but the link in the page is wrong (localhost, http instead of https).The generated URL points at the wrong host or pathFix
- 1
What does the error look like?
404 Not Found for /storage/avatars/photo.jpgStorage::url() returns a link that opens a broken image
Cause 1 of 3
The symbolic link was never created on this server
1Check
The link is created by a command, not by git or by composer install. A new server, a new release directory or a container image built without the command has no link.
ls -ld public/storage2Fix
Create the link with the Artisan command, and put the command in your deploy script so every release gets it.
php artisan storage:link3Verify
The link now exists and a stored file opens in the browser.
ls -ld public/storage
curl -I https://example.com/storage/avatars/photo.jpgConfirmed by laravel.com
Cause 2 of 3
The file was written to the private local disk, not the public one
1Check
In Laravel 12 the default local disk root is storage/app/private. Only the public disk stores into storage/app/public, which is the folder the link exposes.
find storage/app -name "photo.jpg"
grep -n "'default'" config/filesystems.php2Fix
Store the upload on the public disk explicitly, as in the first line below.
$path = $request->file('avatar')->store('avatars', 'public');3Verify
The new upload lands in storage/app/public and its URL opens.
find storage/app/public -name "*.jpg" | head -3Confirmed by laravel.com
Cause 3 of 3
The generated URL points at the wrong host or path
1Check
For the local driver, Storage::url() prepends the url option of the disk. That option is built from APP_URL in the default config, so a copied .env with a local APP_URL gives local links.
grep -n "APP_URL" .env
grep -n "'url'" config/filesystems.php2Fix
Set APP_URL to the real public address, then clear the cached config.
# .env
APP_URL=https://example.com
php artisan config:clear3Verify
Reload the page and open the image link; it now starts with your real domain.
curl -I https://example.com/storage/avatars/photo.jpgConfirmed by laravel.com
How do I stop it coming back?
- Add php artisan storage:link to the deploy script, next to the migrate step.
- Keep the uploaded files outside the release folder if you deploy into a new directory each time, and link that folder.
- Use the disk name in every store() and Storage call so the code does not depend on the default disk.
- Set APP_URL per environment, never copy the local value to the server.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Composer says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack end
Why a Filament panel feels slow on a Laravel server
The panel is fast on a small demo and slow once there are many resources, pages and widgets
A slow Filament panel on a server is most often running without the production caches.
3 causes, each with a fixBack end
Intervention Image will not save the file in a Laravel app
Can't write image data to path (/var/www/app/public/uploads/photo.jpg)
Intervention Image writes straight to a file path.
3 causes, each with a fixBack end
Laravel file upload returns 413 behind nginx
413 Content Too Large
A 413 means a limit refused the request body before Laravel could use it.
3 causes, each with a fixBack end
Laravel says the bootstrap/cache directory must be present and writable
The /var/www/app/bootstrap/cache directory must be present and writable.
Laravel writes its package manifest into bootstrap/cache and throws when that folder is missing or the current user cannot write to it.
2 causes, each with a fixBack end
Carbon::now() and now() return the wrong hour in Laravel
created_at values do not match the local time
Carbon::now() uses the PHP default timezone, and Laravel sets that from app.timezone in config/app.php on every boot.
3 causes, each with a fix