Troubleshooting Lambda Web Functions

Start with the resource state, the HTTP response, and the logs for the request. Web Functions expose separate state for the function, revision, endpoint, and each Region of a MultiRegion or PerRegion endpoint. A failure in one resource does not always change the state of the others.

Collect diagnostic information

Deployment and startup issues

To avoid repeat deployment failures, validate configuration and startup in a test revision before you create a production revision.

CLI and package errors

HTTP request failures

Request header limits

Two limits apply to request headers. Lambda limits the header block to 128 KiB and rejects larger requests before they reach your function. The Node.js HTTP server in your function also limits the number of header lines it accepts. Both return HTTP 431 Request Header Fields Too Large, as shown in the following table. For the platform limits, see Header limits.

The size limit counts every byte of the request head as the client sends it. This includes the request line, every header line (including Host and any headers the client library adds), and the line terminators. Headers that Lambda adds do not count toward the size limit.

When a request exceeds the size limit, Lambda rejects it before it reaches your function, so the request produces no invocation and no application log entry. The lambda-web-error-type response header identifies the cause.

The Node.js count limit counts header lines, not distinct header names. A header that is repeated three times counts three times. As a result, a request that accumulates x-forwarded-for or tracing headers through a chain of proxies can reach the limit. No single header needs to look unusual for this to happen. The limit is measured on the request your function receives, which includes the headers Lambda adds. As a result, a client sending slightly fewer than 1,000 header lines can reach it. When that happens, the request reaches your execution environment, and the Node.js server rejects it during parsing. Your handler does not run. The response carries the lambda-web-request-id and lambda-web-logstream headers, but it does not carry the lambda-web-error-type header.

If your application must accept more header lines than the Node.js default allows, raise the Node.js limit in your server code. Set server.maxHeadersCount to the number of header lines to accept, or set it to 0 to disable the Node.js count check. The 128 KiB size limit still applies.

const server = http.createServer(handler);
server.maxHeadersCount = 2000;
server.listen(port, host);

You do not need to change the Node.js header size limit. The managed Node.js runtimes set it to match the platform limit, so the platform limit applies to header size. You cannot raise the platform limit from application code.

To stay within the limits, move bulk state out of headers and into the request body, trim cookies, and collapse redundant proxy and tracing headers before the request reaches the endpoint. If a CloudFront distribution sits in front of the endpoint, forward only the headers your application needs in the origin request policy.

Web Function error types

When a request to a Web Function endpoint fails, Lambda returns a lambda-web-error-type response header that identifies what went wrong. The value uses the format <Prefix>.<ErrorReason>: the prefix tells you where the error occurred, and the reason specifies the cause.

For example, Runtime.RequestTimeout means the managed runtime reported that your function did not respond within its configured timeout, and Application.InitCodeError means your own initialization code threw an error.

Lambda includes the lambda-web-error-type header when the error was caused by the request itself or by your function, its configuration, or its code. Lambda omits the header for internal service errors and for authorization failures, so that no detail is revealed to an unauthorized caller. A value indicates a problem on the path between the Lambda platform and your function. On the request path, the error identifies where the request failed. On the response path, use the value together with your application telemetry to understand what happened.

For the throttling metrics that identify which limit applied (for the Platform.AccountRequestThrottle, Platform.EndpointRequestThrottle, Platform.AccountActiveVCPUArm64Throttle, and Platform.EndpointMaxEnvThrottle error types), see Regional usage and throttling metrics.

Logs or metrics are missing

If no application logs appear at all, the execution role might lack Amazon CloudWatch Logs permissions. Attach the AWSLambdaBasicExecutionRole managed policy to the execution role, or grant logs:CreateLogGroup, logs:CreateLogStream, and logs:PutLogEvents. For the required permissions, see Execution role.

Code storage and encryption issues

Issues with MultiRegion and PerRegion endpoints

Use the regionalEndpoints field to identify the affected Region. Compare its stateReason and updateStatusReason with the healthy Regions. Check Regional quotas, AWS KMS key replicas, runtime availability, and the revision's replication state. After correcting the cause, repeat the endpoint update. For the replication model, see Multi-Region deployment.

For a MultiRegion endpoint, latency-based routing (which directs requests to the Region with the lowest measured latency) doesn't guarantee that every request goes to the lowest-latency Region. Test from the affected client location and inspect the application logs to determine which Region handled the request. For a PerRegion endpoint, also verify your external DNS or front-door routing configuration.

Networking and connectivity issues

Most connectivity problems come from a serving revision that has no connector reference or references an older connector version, or from connector subnets, security groups, or routes that block the traffic.

Use the following sequence to isolate a connectivity problem:

Common symptoms include the following.

There is no interactive access to a Web Function execution environment. Use application logs, endpoint response headers, resource state fields, CloudWatch metrics, and VPC Flow Logs to diagnose failures.

Prepare an escalation bundle

If the preceding checks do not identify the cause, collect the following information before opening an AWS Support case. This lets the support engineer correlate the control-plane operation, Regional deployment, request, and telemetry:

Related information