How to Tell Whether an Immich Error Comes From the Client or Server
Tell whether an Immich error is client-side or server-side by reproducing the same action with one variable changed and following the failed request through the path.
A mobile banner that says โserver errorโ can still originate from client state, TLS, a reverse proxy, or a request the server rejected correctly. Likewise, a browser-only failure does not prove the browser is broken. Fix the account, asset, and action; compare clients and routes; then use status codes and synchronized logs to locate the first failing layer.
Reproduce the Same Action on a Second Client
Choose one deterministic action such as logging in, opening a known asset, uploading the same small photo, or running the same search. Repeat it with the same account on a browser and mobile client while keeping the network route unchanged. Record exact time and result for both attempts.
A current Immich report where an Android client failed while other access paths were tested illustrates the value of cross-client comparison. The cause in one thread does not generalize, but a client-specific result sharply narrows where to inspect next.
If every client fails the same action at the same time, server, database, storage, or shared network path moves up the list. If only one client fails while another succeeds through the same endpoint, check client version, cached state, permissions, local certificate trust, and the exact request that differs.
Change the Route Without Changing the Account or Asset
Next compare a trusted local route with the normal reverse-proxy, VPN, tunnel, or remote route. Use the same account and action. A local success plus remote failure points away from the media record itself and toward DNS, TLS, proxy, firewall, or upstream-routing layers.
The ZimaSpace guide to local-versus-remote path diagnosis explains why LAN success and internet success are different proofs. Apply that boundary to Immich before reinstalling a mobile app or rebuilding the server.
If both routes fail identically, stop changing proxy settings and inspect the application-side request. If only the proxy route fails, capture proxy status, TLS result, upstream response, and timeout. This single-variable comparison prevents a client message from sending the investigation into the wrong layer.
Use Status Codes as Clues, Not Final Verdicts
HTTP status classes help classify where to look, but they do not automatically identify the component that caused the condition. A 4xx often means the request, authentication, or authorization was not acceptable; a 5xx indicates a server-side component could not fulfill the request. Proxies can generate either class before Immich sees the request.
The access-log field guide highlights status code, URL path, request time, remote host, and request identifiers as useful troubleshooting fields. Capture those values for the one failing action instead of scanning thousands of unrelated lines.
If the proxy records a 502 or timeout with no matching Immich request, follow the upstream path. If Immich logs a request and returns a deterministic 4xx, inspect authentication, permissions, or request content. If the client reports failure but all server-side layers show 2xx, inspect client parsing, local cache, or follow-up requests.
Correlate Error Rate, Latency, and Server Logs at One Timestamp
One failed request can be an outlier. Reproduce the action five to ten times and record success rate and latency while watching the relevant server and proxy logs. If errors rise during resource pressure or queue spikes, the server may be intermittently unavailable even though a second attempt succeeds.
The Better Stack overview of errors and latency as service signals separates error rate from latency and traffic. That framing helps distinguish a single malformed client request from a server path that degrades only under load.
If the server logs contain the same exception for multiple clients, treat it as server-side until disproved. If the server never sees the failing request, trace DNS, TLS, proxy, and client networking. If only one client generates a different request shape, update or reset that client after preserving enough evidence to confirm the difference.
Make the Final Judgment With a Two-by-Two Test
Use two clients and two routes: browser-local, browser-remote, mobile-local, and mobile-remote. Keep the same account and test asset. This matrix separates client-specific failures from route-specific failures and from server failures that affect every combination.
A client cause is supported when one client fails on both routes while another passes. A route cause is supported when both clients fail only through one route. A server cause is supported when all four reproduce the same application error and the server logs show the same failing operation.
After fixing the identified layer, rerun all four cells and one restart of the affected component. Stop when the original failing cell passes without breaking the controls. Escalate with the matrix, timestamps, HTTP statuses, proxy and server log excerpts, client versions, and one reproducible request rather than a generic screenshot.
Recommended products
Support & Tips
More to Read
How to Optimize Immich Database Connections for Concurrent Containers
Do not raise max_connections first. Measure Immich sessions, total every container's demand, preserve admin headroom, and tune only the proven bottleneck.
How to Prevent Duplicate Jobs or Imports in Immich
Separate repeated jobs from duplicate assets. Use one canonical ingestion path, control retries and path changes, then test re-entry on a small cohort.
How to Repair Immich After Its Database Volume Fills Up
Never delete PostgreSQL WAL to free space. Stop Immich writes, preserve database state, add safe capacity, recover PostgreSQL, then prevent recurrence.
