NEL

The HTTP NEL response header configures Network Error Logging, instructing the browser to collect and send reports about network-level failures and successes for an origin.

Usage

Network errors like DNS resolution failures, TCP connection resets, and TLS handshake problems are invisible to application-level JavaScript. A page load fails and the server never receives the request, leaving operators blind to infrastructure problems affecting real users.

The NEL header gives servers a way to opt in to receiving reports about these failures. The server sends a JSON-formatted policy in the NEL header, specifying where reports go, how long the policy lasts, and what fraction of requests to sample. The browser stores the policy and begins collecting network error data for the origin. Reports are delivered asynchronously to an endpoint defined by the Report-To header using the Reporting API.

NEL captures errors at the network layer before the HTTP response is formed. DNS errors, TCP timeouts, TLS certificate failures, and connection resets all generate reports. The reporting covers the full request lifecycle from DNS resolution through response completion. Successful requests are also reportable, controlled by a separate sampling fraction, enabling operators to compare error rates against total traffic volume.

The policy persists in the browser for the duration specified by max_age. Setting max_age to 0 removes a previously registered policy for the origin. The include_subdomains flag extends coverage across all subdomains without requiring separate policies for each.

NEL works alongside the Report-To header. The report_to directive in the NEL policy references a named endpoint group defined in the Report-To header. Without a matching Report-To configuration, NEL reports have no delivery target.

Directives

report_to

The report_to directive names the endpoint group receiving the reports. The group is defined in a corresponding Report-To header. Required when registering a new policy. Optional when removing a policy by setting max_age to 0.

max_age

The max_age directive sets the policy lifetime in seconds. The browser enforces the policy until the duration expires. A value of 0 removes the policy from the browser's cache for the origin. Negative values are invalid and cause a parse error.

include_subdomains

The include_subdomains directive is a boolean controlling whether the policy applies to all subdomains of the origin. Defaults to false when omitted.

success_fraction

The success_fraction directive sets the sampling rate for reports about successful requests. The value is a number between 0.0 and 1.0. A value of 0.0 (the default) disables reporting on successful requests. A value of 1.0 reports every successful request. Values outside the range cause a parse error.

failure_fraction

The failure_fraction directive sets the sampling rate for reports about failed requests. The value is a number between 0.0 and 1.0. A value of 1.0 reports every failure. A value of 0.0 disables failure reporting. Defaults to 1.0 when omitted. Values outside the range cause a parse error.

request_headers

The request_headers directive is a list of request header names whose values are included in the generated NEL reports. This extension is supported in Chromium-based browsers and is backwards-compatible with existing NEL policies omitting the field.

response_headers

The response_headers directive is a list of response header names whose values are included in the generated NEL reports. Useful for including infrastructure identifiers (like server names or cache node IDs) in error reports to help isolate which serving component experienced the failure.

Example

A basic NEL policy reporting all network failures to an endpoint group called network-errors. The policy lasts 24 hours (86400 seconds). All failures are reported (failure_fraction defaults to 1.0) and no successful requests are sampled.

NEL: {"report_to":"network-errors","max_age":86400}
Report-To: {"group":"network-errors","max_age":86400,
  "endpoints":[{"url":"https://collector.example.re/nel"}]}

A policy covering all subdomains with explicit sampling rates. Half of all failures and 1% of successful requests generate reports. The low success fraction keeps report volume manageable while still providing a baseline for comparison.

NEL: {"report_to":"nel","max_age":604800,
  "include_subdomains":true,"success_fraction":0.01,
  "failure_fraction":0.5}

A policy including response header values in reports. The response_headers field instructs the browser to attach the server identification header to each report, helping operators identify which infrastructure node experienced the error.

NEL: {"report_to":"nel","max_age":86400,
  "failure_fraction":1.0,
  "response_headers":["Server","X-Served-By"]}

Removing a previously registered NEL policy for the origin by setting max_age to 0.

NEL: {"report_to":"nel","max_age":0}

Takeaway

The NEL header configures browser-side collection of network error reports, giving operators visibility into DNS, TCP, and TLS failures before the HTTP layer. Reports are delivered via the Reporting API to endpoints defined in the Report-To header.

See also

• Network Error Logging (W3C)
• Network Error Logging: request_headers and response_headers (Chrome Status)
• Report-To
• Reporting-Endpoints
• HTTP headers