# Laravel Storage Link 404 on Nginx? The Production Fix

Locally everything looks fine. You upload a file, the image opens, the avatar shows up. Push the same project to a production box behind Nginx and URLs like `/storage/avatars/user1.jpg` start returning 404. Sometimes it only breaks after a fresh deploy, while the previous release still worked.

If you're hunting a **Laravel storage link 404** on Nginx, it's usually one of these: the symlink was never created, Nginx is blocking it with `disable_symlinks`, the permission or owner is wrong, the document root does not point at `public/`, you're stuck on shared hosting, or a zero-downtime deploy never wired the link to shared storage. This article walks through each case with exact diagnostic and fix commands, compares `Storage::url` and `asset`, and ends with a deploy pattern that stops the problem coming back.

## Short answer if you're in a hurry

From the project root (not from inside `public/`):

```bash
mkdir -p storage/app/public
php artisan storage:link --force
ls -la public/ | grep storage
# you want something like:
# lrwxrwxrwx ... storage -> ../storage/app/public
```

Then check Nginx:

```bash
sudo nginx -T 2>/dev/null | grep disable_symlinks
# should not be disable_symlinks on
sudo nginx -T 2>/dev/null | grep -E '^\s*root\s+'
# should end in .../public, not the project root
```

If the symlink looks right and you still get 404, use the diagnosis table below. The rest of the article unpacks every scenario.

## What is public/storage anyway?

According to the [Laravel filesystem docs](https://laravel.com/docs/12.x/filesystem#the-public-disk), files that should be reachable from the web live in `storage/app/public`, and you create a symbolic link from `public/storage` to that path:

```
/var/www/your-app/
├── storage/
│   └── app/
│       └── public/          ← the real files live here
│           ├── avatars/
│           │   └── user1.jpg
│           └── uploads/
└── public/                  ← Nginx document root
    ├── index.php
    └── storage -> ../storage/app/public   ← symlink
```

When a user opens `https://example.com/storage/avatars/user1.jpg`, Nginx looks under `public/storage/...`. Because `storage` is a symlink, it finds the real file. If the symlink is missing, or Nginx refuses to follow it, you get 404.

`php artisan storage:link` reads the `links` array in `config/filesystems.php`:

```php
'links' => [
    public_path('storage') => storage_path('app/public'),
],
```

Add more links there if you need them:

```php
'links' => [
    public_path('storage') => storage_path('app/public'),
    public_path('images')  => storage_path('app/images'),
],
```

## Fast diagnosis: which scenario is it?

Before you start clearing caches at random, use this table:

| Scenario | Signal | Diagnostic command | Healthy result | Failure result |
|---|---|---|---|---|
| 1. No symlink | `/storage/...` is 404 | `ls -la public/ \| grep storage` | `storage -> ../storage/app/public` | `drwxr-xr-x ... storage` (real directory) |
| 2. `disable_symlinks on` | 404 + log `symlink not allowed` | `sudo nginx -T 2>/dev/null \| grep disable_symlinks` | `off` or absent | `disable_symlinks on` |
| 3. Wrong permission/owner | 404 + log `permission denied` | `stat -c "%U:%G %a" storage/app/public` | e.g. `www-data:www-data 755` | `root:root 700` |
| 4. Wrong document root | `/storage/...` 404 but `/` works | `grep root /etc/nginx/sites-enabled/*` | `root .../public;` | `root .../your-app;` without `/public` |
| 5. Shared hosting | No symlink, File Manager only | No SSH | Manual symlink or cron | Cannot create the link |
| 6. Zero-downtime deploy | New release 404, previous OK | `ls -la releases/ && readlink current` | `public/storage` points at shared | Each release has its own link |
| 7. Two Docker containers | Correct symlink, still 404 | `docker inspect` on app and nginx | `storage` volume mounted on both | Mounted only on app |

## Scenario 1: the symlink was never created (most common)

### Diagnosis

```bash
ls -la /var/www/your-app/public/ | grep storage
```

If you see `drwxr-xr-x ... storage`, that is a real directory, not a symlink. You want:

```
lrwxrwxrwx 1 www-data www-data 23 Nov  3 12:00 storage -> ../storage/app/public
```

### Fix

```bash
cd /var/www/your-app
mkdir -p storage/app/public
php artisan storage:link
```

If something already exists at `public/storage` and you get `File already exists`:

```bash
# if nothing important is inside:
rm -rf public/storage
php artisan storage:link

# or without a manual delete:
php artisan storage:link --force
```

Newer Laravel versions also accept `--relative` for a relative link. The same pattern works in a container entrypoint:

```bash
mkdir -p storage/app/public
php artisan storage:link --force || echo "storage:link failed"
```

Then verify the contents:

```bash
ls -la public/storage/
# should list whatever is in storage/app/public
```

One note for zero-downtime deploys: do not blindly run `storage:link` in every release if you keep a separate shared path. The link should point at shared storage, not at `storage` inside that release. Scenario 6 covers that.

## Scenario 2: the symlink exists, but Nginx blocks it

Per the [Nginx `disable_symlinks` docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#disable_symlinks), when the option is `on`, access is denied if any part of the path is a symbolic link.

```bash
sudo nginx -T 2>/dev/null | grep disable_symlinks
```

If you see `disable_symlinks on`:

```nginx
server {
    # ...
    disable_symlinks off;
}
```

Then:

```bash
sudo nginx -t
sudo systemctl reload nginx
```

Nginx defaults to `off`, but some distros or hardened templates flip it to `on`.

Turning it off removes one defense against symlink attacks. Make sure `root` points only at your project's `public/` directory, and that the app cannot upload outside `storage/app/public` or plant its own symlinks there.

## Scenario 3: wrong permission or owner

```bash
ls -la storage/app/public/
stat -c "%U:%G %a" storage/app/public/
```

If the owner is `root:root` and the Nginx or PHP-FPM worker runs as `www-data`, the file cannot be read. Common cases:

- `root:root 700`: the worker cannot enter the directory
- correct owner, but file mode `600`: others cannot read
- owner `forge:forge` while the worker is `www-data`: group mismatch

Typical fix on Debian or Ubuntu:

```bash
sudo chown -R www-data:www-data /var/www/your-app/storage/app/public
sudo find /var/www/your-app/storage/app/public -type d -exec chmod 755 {} \;
sudo find /var/www/your-app/storage/app/public -type f -exec chmod 644 {} \;
```

(On some panels the user is `www`, not `www-data`. Use whichever user PHP-FPM actually runs as.)

If SELinux is enforcing (CentOS, RHEL, AlmaLinux):

```bash
getenforce
# Enforcing

sudo chcon -R -t httpd_sys_rw_content_t /var/www/your-app/storage/app/public
# or:
sudo setsebool -P httpd_read_user_content 1
```

Without the right context, even correct chmod values can still get blocked.

Test as the web server user:

```bash
sudo -u www-data cat /var/www/your-app/storage/app/public/avatars/user1.jpg | head -c 10
# you should see the first few bytes (JPEG or PNG magic bytes, for example)
```

## Scenario 4: wrong document root

```bash
sudo nginx -T 2>/dev/null | grep -E '^\s*root\s+'
# or
grep root /etc/nginx/sites-enabled/*
```

You want:

```nginx
root /var/www/your-app/public;
```

Not this:

```nginx
# wrong: project root, missing /public
root /var/www/your-app;
```

If `root` points at the project directory, Nginx looks for `/storage` in the wrong place and returns 404, even when the homepage still works because of other rewrite rules. After fixing it:

```bash
sudo nginx -t
sudo systemctl reload nginx
```

## Scenario 5: shared hosting (cPanel / Plesk)

On shared hosting you often have limited SSH, a fixed `public_html` document root, and either no usable `php artisan storage:link` or a PHP CLI binary in an odd path.

**Option 1: manual symlink or cron**

In the cPanel File Manager, open `public_html`. If `storage` exists as a normal directory, remove or rename it, then create a symlink to `../storage/app/public` (one level above `public_html`, where your app's `storage` usually lives).

Or from cron:

```bash
cd /home/USER/your-app && /usr/local/bin/php artisan storage:link
```

Ask the host for the PHP CLI path; `/usr/local/bin/php` or `/opt/cpanel/ea-php83/root/usr/bin/php` are common.

**Option 2: serve files through Laravel (last resort)**

```php
// routes/web.php
Route::get('/storage/{path}', function (string $path) {
    abort_unless(
        Storage::disk('public')->exists($path),
        404
    );

    return Storage::disk('public')->response($path);
})->where('path', '.*');
```

That path goes through PHP, is slower, hits middleware, and is risky if you do not constrain it carefully. Prefer a real symlink. Laravel is not designed for shared hosting; if the host will not allow one, talk to support or move to a VPS.

## Scenario 6: zero-downtime deploy breaks the symlink

With Capistrano, Deployer, Envoyer and similar layouts you usually have:

```
/var/www/your-app/
├── current -> releases/20261103120000
├── releases/
│   ├── 20261102100000/
│   └── 20261103120000/
└── shared/
    └── storage/
        └── app/
            └── public/
```

If every release does this:

```bash
# wrong: relative link inside that release
ln -s ../../../storage/app/public "$RELEASE/public/storage"
```

new uploads land in the wrong place, or the new `current` no longer sees older files.

The right pattern is for `public/storage` to always point at shared storage:

```bash
SHARED_DIR=/var/www/your-app/shared
RELEASE_DIR=/var/www/your-app/releases/20261103120000

mkdir -p "$SHARED_DIR/storage/app/public"
ln -sfn "$SHARED_DIR/storage/app/public" "$RELEASE_DIR/public/storage"
ln -sfn "$SHARED_DIR/.env" "$RELEASE_DIR/.env"
```

In a simple Envoy task you use the same idea: create the shared path, then `ln -sfn` into `public/storage` inside the release. Uploads then stay visible across every release.

If you build the deploy script with GitHub Actions, we walk through it in the [automated Laravel deployment with GitHub Actions guide](https://captaincode.tech/en/blog/github-actions-automated-deployment). After switching releases, rebuild config and the other caches too; if `.env` changes are the part that bites you, see the [Laravel .env changes and config:cache guide](https://captaincode.tech/en/blog/laravel-env-changes-not-working-config-cache).

## Scenario 7: Nginx and the app in separate containers

In Docker or Kubernetes stacks you often have one PHP-FPM container and a separate Nginx container. The symlink inside the app container can be correct, but if the `storage` volume is not mounted into Nginx, Nginx cannot reach the target and returns 404.

Diagnosis:

```bash
docker inspect <app_container> --format '{{json .Mounts}}'
docker inspect <nginx_container> --format '{{json .Mounts}}'
```

Simple docker-compose fix:

```yaml
services:
  app:
    volumes:
      - app-storage:/var/www/html/storage
      - ./public:/var/www/html/public

  nginx:
    volumes:
      - app-storage:/var/www/html/storage:ro
      - ./public:/var/www/html/public:ro

volumes:
  app-storage:
```

The same volume must exist on both services. Prefer read-only (`:ro`) on Nginx. In Kubernetes the same idea is a shared PVC: writable for the app, read-only for Nginx.

And again: Nginx `root` should be only `public/`. If a user upload can create a symlink into system paths, leaving `disable_symlinks off` is a real risk.

## Storage::url, asset and APP_URL

Sometimes the symlink is fine and the URL is wrong:

| Method | Typical output | When to use it | Common trap |
|---|---|---|---|
| `asset('storage/avatars/user1.jpg')` | `https://example.com/storage/...` | In Blade | Wrong `APP_URL` produces the wrong host |
| `Storage::disk('public')->url('avatars/user1.jpg')` | same shape | In a controller or job | The `public` disk must be configured |
| `Storage::url('...')` | depends on the default disk | Only when default is `public` | Changing the default breaks URLs |
| Hard-coded URL | fixed string | Never | A domain change means hunting strings |

In `config/filesystems.php` the `public` disk usually looks like this:

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

So `APP_URL` must match the host users actually open. If the site is on `www` and `APP_URL` is not, or the other way around, you can end up with 404s or odd redirects. After editing `.env`, rebuild the config cache.

If the front-end also falls apart after deploy, Vite may be involved; keep the [Laravel Vite manifest not found guide](https://captaincode.tech/en/blog/laravel-vite-manifest-not-found-production) next to this one.

## A deploy script that does not break the symlink

```bash
#!/usr/bin/env bash
set -euo pipefail

REPO_DIR="/var/www/your-app"
SHARED_DIR="$REPO_DIR/shared"
NEW_RELEASE="$REPO_DIR/releases/$(date +%Y%m%d%H%M%S)"

git clone --depth 1 --branch main "$REPO" "$NEW_RELEASE"

mkdir -p "$SHARED_DIR/storage/app/public"
ln -sfn "$SHARED_DIR/.env" "$NEW_RELEASE/.env"
ln -sfn "$SHARED_DIR/storage/app/public" "$NEW_RELEASE/public/storage"

(
  cd "$NEW_RELEASE"
  composer install --no-dev --optimize-autoloader --no-interaction
  php artisan migrate --force
)

ln -sfn "$NEW_RELEASE" "$REPO_DIR/current"

(
  cd "$REPO_DIR/current"
  php artisan config:cache
  php artisan route:cache
  php artisan view:cache
)

sudo systemctl reload php8.3-fpm

# keep a few recent releases
cd "$REPO_DIR" && ls -dt releases/* | tail -n +6 | xargs -r rm -rf
```

Here `public/storage` is wired to shared storage once and reused across releases. You do not need `storage:link` inside each release, because you already created the correct link.

## FAQ

**1. php artisan storage:link says File already exists. What now?**

Something named `storage` already exists under `public/` (a file, a directory or an old link). If nothing important is inside it, run `rm -rf public/storage` and then `php artisan storage:link`. Or use `php artisan storage:link --force`. Laravel also ships `storage:unlink` when you need to remove the link.

**2. The symlink looks correct, but the image is still 404. Why?**

Four frequent causes: `disable_symlinks on` in Nginx, permission or SELinux issues, a wrong `root` or `try_files` setup, and a browser or CDN cache holding an old URL. Start with the diagnosis table at the top and read the Nginx error log.

**3. What can I do on shared hosting without SSH?**

In the cPanel or Plesk File Manager, remove the real `storage` directory inside `public_html` and create a symlink to `../storage/app/public`. If the File Manager will not create symlinks, use cron with the correct PHP CLI path. Serving files through a Laravel route is a last resort and a poor fit for production.

**4. Why does the link break after every deploy?**

Because the deploy script creates a fresh symlink inside each release that does not point at shared storage. `public/storage` should always point at a shared path such as `shared/storage/app/public`, so uploads survive across releases.

**5. In Docker with separate Nginx and app containers, how should the symlink work?**

A symlink inside the app container is not enough. The `storage` volume must also be mounted into the Nginx container (preferably read-only). Otherwise Nginx never reaches the real file and `/storage/...` returns 404.


One-line summary: make sure `public/storage` is a symlink to `storage/app/public` (or the shared equivalent), Nginx is allowed to follow it, permissions are correct, the document root is `public/`, and atomic deploys point the link at shared storage.

If you'd rather not wrestle with Nginx, deploys and permissions yourself, we can set up your Laravel server and look after the project. Details are on the [website security and maintenance](https://captaincode.tech/en/services/security-maintenance) page, and you can send us the project from there.

Got a question or stuck somewhere? Ask in the comments.

