Immich Upload Errors: 413, 502 and Images That Won't Load

We earn commissions when you shop through the links below. Learn more

Guide · Immich

Pinned version: Immich v3.3.5 (GitHub release). Last checked: 2026-10-28.

Most Immich upload errors come from what sits between the app and the server. A 413 means a reverse proxy rejected a file as too large: raise its body-size limit. A 502 means the proxy couldn't reach Immich: check that the immich_server container is running and that the proxy points to port 2283. Images that upload but don't display usually mean their background jobs haven't finished or failed. Check Administration → Jobs.

413 Request Entity Too Large

nginx returns 413 when a request body is larger than client_max_body_size (nginx docs, checked 2026-10-28). Videos hit this first, which is why the Immich FAQ answers "Why are only photos and not videos being uploaded?" with "set your reverse proxy to allow large requests".

Immich's reverse proxy example for nginx uses:

nginx
client_max_body_size 50000M;
proxy_request_buffering off;
client_body_buffer_size 1024k;
proxy_read_timeout 600s;
proxy_send_timeout 600s;
send_timeout       600s;

The FAQ also says to check the proxy's free disk space: some proxies cache uploads to disk first, and the request fails when the disk is full.

Cloudflare: the FAQ notes that Cloudflare Tunnel has a 100 MB file limit "that cannot be changed". Cloudflare's own docs list a 100 MB maximum upload size on the Free and Pro plans (Cloudflare docs, checked 2026-10-28). If your videos are bigger, Immich recommends a different network setup, such as Tailscale or WireGuard; see Tailscale vs WireGuard vs Cloudflare Tunnel.

Uploads stop after about a minute (Traefik)

Immich's docs say Traefik's default 60-second responding timeout makes video uploads stop after one minute, with error 499. Raise readTimeout and idleTimeout on the entrypoint, for example to 600s (see the Traefik example in the reverse proxy docs).

502 Bad Gateway

A 502 comes from the proxy, not from Immich: it couldn't get a response from the upstream server. Check, in order:

  1. docker compose ps: is immich_server running, or restarting?
  2. docker logs immich_server: look for the error that stopped it, for example a database connection error.
  3. The proxy target: the Immich examples proxy to http://<backend>:2283.
  4. The path: Immich must be served at the root of a (sub)domain. The docs say it does "not support being served on a sub-path" such as /immich.

For database startup errors such as wrong ownership of the data directory, the FAQ says NTFS and exFAT/FAT32 filesystems are not supported for the database.

Images uploaded but show an error or a grey tile

Each upload starts background jobs: metadata extraction, thumbnail generation (three per asset: blurred, preview and thumbnail), machine learning and, if enabled, the storage template (Jobs and Workers). Until thumbnail generation finishes, there's nothing to show. Check:

If the image still won't load in the browser after a fix, Immich's docs mention aggressive browser caching. Do a hard reload with an empty cache.

Mobile app can't connect after setting up HTTPS

If your proxy uses the Let's Encrypt http-01 challenge, the docs say to make sure /.well-known/immich is routed to Immich. Otherwise the mobile app "may run into connection issues".

Before you change proxy settings, make sure your backups are current: Immich backup and restore.

Related: install Immich with Docker Compose · Tailscale vs WireGuard vs Cloudflare Tunnel · Immich backup and restore

Sources

Related guides