Distributed systems

nginx 499 — the immediate client closed the request

Written and reviewed by Sahil Srivastav

nginxClient cancellationAccess logs

What this error actually means

499 is nginx’s internal status for a client closing the connection while nginx is processing the request. It appears in access logs; it is not a standard HTTP error page that nginx successfully sends to that departed client. The client already disconnected, so the useful question is why it stopped waiting.

Client means nginx’s immediate downstream peer. Behind a CDN or load balancer, that peer may be another proxy whose deadline expired, even when the browser remains connected to the outer hop. One operation can consequently appear as 504 at the edge, 499 at nginx and a later 200 completion in the application log.

Individual cancellations are normal: users navigate away, requests are superseded and mobile connections disappear. A sharp rise at one elapsed duration is different. It suggests a configured deadline shorter than the work’s actual lifetime. Measure the abandoned work as well as the log count; harmless cancellation and capacity-destroying orphan work require different responses.

Causes, most common first

1An outer request deadline expires first. The client or gateway waits less time than nginx and the application. It closes the downstream exchange; nginx records that event while the true bottleneck may be a query, queue or dependency much further inside.
2The frontend deliberately cancels obsolete work. Autocomplete, navigation and component cleanup commonly abort requests. A healthy cancellation should release request-owned resources promptly. Treating every such event as a server outage creates noisy alerts that obscure real regressions.
3Retries replace requests that are still running. A caller gives up and starts another attempt, but the server does not cancel the original. Multiple copies consume the same limited resources, making the next attempt even more likely to exceed the deadline.
4A slow or interrupted client path closes the connection. Mobile handoffs, local proxy policies and connection drops can abort a request independently of backend health. Compare client networks and regions before attributing every disconnected socket to a slow database.

When you see it

The nginx access log shows 499 while the browser reports a timeout or cancellation.
Request durations cluster near a client SDK or outer load balancer’s configured limit.
Database or application work continues after the matching access-log entry.
499s increase during slow queries or deployments without a corresponding rise in application exceptions.

How to diagnose it

Step 1

Add a purpose-built timing log

Place this example log_format in nginx’s http context and use it with an access_log directive. Include your existing request identifier if present. Upstream variables can contain several values when retry attempts occur, so preserve them as quoted fields.

log_format aborts '$request_id status=$status rt=$request_time upstream="$upstream_addr" us="$upstream_status" urt="$upstream_response_time"';

Step 2

Reproduce one cancellation in staging

Use an endpoint deliberately slower than the two-second client budget. curl reports its own timeout; nginx may record 499 when it observes the disconnect before completing the response. The exact status can depend on how far the response progressed.

curl -v --max-time 2 https://staging.example.com/test/slow

Step 3

Find the corresponding record at the outer hop

Match the operation identifier, selected origin and timestamps. If the outer proxy returned 504 at its exact limit, that is the client nginx is describing. Changing nginx’s timeout cannot increase the outer proxy’s maximum.

Step 4

Verify when request-owned work actually stops

Follow the trace through application tasks and database activity after the disconnect. Count remaining occupied pool slots. A cancellation callback that logs immediately but leaves the underlying query running has not recovered the capacity.

The fix

When latency exceeds the intended budget, fix the dominant wait and reject excess work early. Align outer and inner deadlines so the application has time to produce a controlled response and clean up before its caller disconnects. Include queueing in the budget; timing only the database call misses work already expired in the queue.

Wire request cancellation into interruptible remote calls and request-scoped tasks, and release resources unconditionally when those operations terminate. Database drivers may need explicit statement cancellation or server-side timeouts. Do not return a connection to the pool while its previous operation is still running.

For deliberate frontend cancellation, keep the behaviour and measure it separately by route and cancellation reason. Debounce unnecessary search requests where appropriate, and avoid generating retries for an operation the user explicitly abandoned.

Do not enable proxy_ignore_client_abort as a general repair. Continuing upstream processing can be correct for an intentional durable operation, but it increases abandoned work for ordinary request-response traffic. Durable jobs should have explicit acceptance, state and recovery semantics instead of depending on an HTTP socket surviving.

How to stop it coming back

Alert on changes in 499 rate together with latency, successful completion and resource occupancy, rather than status count alone.
Keep a cancellation test that asserts request-owned database or HTTP pool leases return after the client disconnects.
Document the outermost deadline and verify deployment draining does not routinely exceed it.

Practise production debugging in a real repository

Reading about a failure and reproducing one are different skills. Gronex ships broken backend repositories with failing test suites that encode the real invariant, so you debug from evidence instead of memorising symptoms.

FAQ

Should I return 499 from my API?

Usually no. Its value here is nginx’s accounting of a peer that has already disconnected. Design ordinary API timeout and cancellation responses using the contract your clients understand; a closed socket cannot receive a new status.

Does 499 prove that the user closed the browser?

No. The immediate peer could be a load balancer, an SDK with a deadline, or a browser aborting one superseded fetch while the page remains open. Identify the peer and correlate the outer logs.

Can a write complete after nginx logs 499?

Yes. Client disconnection does not guarantee transaction rollback. Preserve operation identifiers and offer outcome lookup for important writes, so a user retry does not accidentally duplicate an already committed action.

504 and competing timeout budgets Abandoned work and pool exhaustion Long-poll connection resets

Other errors engineers hit next to this one

Full error and symptom index →