Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Uploaded images return 404 after deploying a Laravel app

Error404 Not Found for /storage/avatars/photo.jpg

Short 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.

  • Applies to Laravel 11, Laravel 12, PHP 8.3, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 | head
  2. 2Match what you see, then jump to its fix

    1. 1ls: cannot access 'public/storage': No such file or directoryThe symbolic link was never created on this serverFix
    2. 2The 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. 3The 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

What does the error look like?

  • 404 Not Found for /storage/avatars/photo.jpg
  • Storage::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/storage

2Fix

Create the link with the Artisan command, and put the command in your deploy script so every release gets it.

php artisan storage:link

3Verify

The link now exists and a stored file opens in the browser.

ls -ld public/storage
curl -I https://example.com/storage/avatars/photo.jpg

Confirmed by laravel.com

Did this fix it?

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.php

2Fix

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 -3

Confirmed by laravel.com

Did this fix it?

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.php

2Fix

Set APP_URL to the real public address, then clear the cached config.

# .env
APP_URL=https://example.com

php artisan config:clear

3Verify

Reload the page and open the image link; it now starts with your real domain.

curl -I https://example.com/storage/avatars/photo.jpg

Confirmed by laravel.com

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.