--- cuppy_hub: aws cuppy_path: reference/lambda/errors.md cuppy_section: docs cuppy_doc: 9030-SAQ0 cuppy_doc_uuid: 7cda6cec-fcdf-4bf6-8368-90b6b24456a4 cuppy_permalink: https://cuppy.io/aws/d/9030-SAQ0 cuppy_version: 4 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/reference/lambda/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 6ae52d069dfcc3bac92b546e3e4a629d880ee579902439541b8d6d115c88cf6f # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # AWS Lambda errors **There are two kinds, and they arrive differently.** *Service errors* (throttling, permissions, payload size, function state) make the `Invoke` call itself fail with an exception name and HTTP status. *Function errors* (your code threw, timed out, or ran out of memory) return HTTP 200 with the `X-Amz-Function-Error` header (SDK: `FunctionError`) set, and an error object in the payload. Check which kind you have first. ## Function errors (HTTP 200 + `FunctionError`) | Message | Cause → fix | Check | |---|---|---| | `Task timed out after 3.00 seconds` (any number) | Ran past the configured timeout. Raise it (default 3 s, max 900 s). If the function is in a VPC and calls the internet or an AWS API, it has no route out: NAT gateway or VPC endpoints (`patterns/lambda-in-vpc.md`). | `aws lambda get-function-configuration --function-name --query [Timeout,VpcConfig]`; the `REPORT` line's `Duration` | | `Runtime.NodejsExit` | The process exited, for example via `process.exit()`. Return from the handler. | Search the code for `process.exit` | | `Couldn't find valid bootstrap(s): [/var/task/bootstrap /opt/bootstrap]` | Custom runtime (`provided.*`) without an executable `bootstrap` at the zip root or in a layer. | `unzip -l function.zip`: `bootstrap` at the root, mode executable | | `{"errorType":"…","errorMessage":"…","trace":[…]}` | An exception your code threw (or an SDK error it did not catch). The `errorType` is the class name, for example `AccessDeniedException` from an AWS call. That is an **execution role** permission problem: `guides/iam/fix-access-denied.md`. | The function's log stream for that request ID | | `Runtime.ImportModuleError`, `Runtime.HandlerNotFound` | Handler setting does not match the deployed file or export. UNVERIFIED in the collected sources. | `aws lambda get-function-configuration --function-name --query Handler` vs `unzip -l function.zip` and the exported name | ## Invoke API exceptions | Exception | HTTP | Cause → fix | Check | |---|---|---|---| | `TooManyRequestsException` | 429 | Concurrency exhausted (account Region quota, reserved concurrency, reserved concurrency 0), or the per-function scaling rate (1,000 new environments per 10 s) exceeded. Retry with backoff. Check `get-function-concurrency` and `get-account-settings`. | `aws lambda get-function-concurrency --function-name `; `aws lambda get-account-settings` → `AccountLimit.ConcurrentExecutions`; the `Throttles` metric | | `ResourceNotFoundException` | 404 | Wrong name, alias, version or Region, or the function was deleted. | `aws lambda list-versions-by-function --function-name --region ` | | `RequestTooLargeException` | 413 | Payload over 6 MB (synchronous) or 1 MB (asynchronous). Pass an S3 reference. | The payload's byte length | | `RecursiveInvocationException` | 400 | Lambda detected a recursive loop and stopped it. Break the trigger cycle. | `aws lambda get-function-recursion-config --function-name `; the trigger and the function's writes | | `InvalidParameterValueException` | 400 | A bad parameter, for example `--payload` without `--cli-binary-format raw-in-base64-out` in CLI v2, so the payload is not valid JSON (UNVERIFIED that this is the reported exception). | The message names the parameter | | `InvalidRequestContentException` | 400 | Body is not valid JSON. | Parse the payload with `JSON.parse` | | `ResourceConflictException` | 409 | `The operation cannot be performed at this time. The function is currently in the following state: Pending`. Create or update in progress: wait (`aws lambda wait function-updated-v2`). | `aws lambda get-function-configuration --function-name --query [State,LastUpdateStatus]` | | `ResourceNotReadyException` | 502 | The function is inactive and the attempt to reactivate it failed. Read `StateReasonCode`. | `aws lambda get-function-configuration --function-name --query [State,StateReasonCode]` | | `EC2ThrottledException`, `EC2UnexpectedException`, `EC2AccessDeniedException` | 502 | Lambda could not set up the function's VPC networking. For access denied: the execution role needs the ENI permissions (`AWSLambdaVPCAccessExecutionRole`). | `aws lambda get-function-configuration --function-name --query StateReasonCode`; the role's ENI permissions | | `ENILimitReachedException` | 502 | The VPC hit the network-interface limit for Lambda. | Service Quotas for VPC network interfaces | | `SubnetIPAddressLimitReachedException` | 502 | No free IP addresses in the configured subnets. Add subnets or larger ones. | `aws ec2 describe-subnets --subnet-ids --query 'Subnets[].AvailableIpAddressCount'` | | `InvalidSubnetIDException`, `InvalidSecurityGroupIDException` | 502 | A configured subnet or security group no longer exists. | `describe-subnets` / `describe-security-groups` on the IDs in `VpcConfig` | | `KMSDisabledException` | 502 | `Lambda was unable to decrypt the environment variables because the KMS key used is disabled`. Enable the key or change it. | `aws lambda get-function-configuration --function-name --query KMSKeyArn`, then `aws kms describe-key --key-id --query KeyMetadata.KeyState` | | `KMSAccessDeniedException`, `KMSInvalidStateException`, `KMSNotFoundException` | 502 | The execution role cannot use the environment's key, or the key is pending deletion or gone. | Same, plus `aws kms get-key-policy` for the execution role | | `InvalidZipFileException` | 502 | The deployment package is not a valid zip. | `unzip -t function.zip` | | `InvalidRuntimeException` | 502 | The runtime or its settings are invalid. For deprecated runtimes, update the function. | `aws lambda get-function-configuration --function-name --query Runtime` | | `ServiceException` | 500 | Internal error. Retry. | A retry succeeds | Asynchronous (`Event`) invocations return **202** on acceptance. Errors after that are retried up to two more times and never reach the caller. Configure an on-failure destination or a dead-letter queue to see them. ## Caller not allowed ``` User: is not authorized to perform: lambda:InvokeFunction on resource: ``` - Same account: the caller's identity policy lacks `lambda:InvokeFunction` on that function ARN (or `…:function::*` for aliases and versions). - A service (S3, EventBridge, SNS) or another account: the **function's resource-based policy** must allow it (`reference/lambda/permissions.md`). ## Resource-based policy errors (`PutResourcePolicy`, `AddPermission`) | Exception | HTTP | Cause → fix | Check | |---|---|---|---| | `PolicyLengthExceededException` | 400 | Policy over 20 KB (20,480 characters). Consolidate statements. The 2026 full-policy support lets one statement cover several principals. | `aws lambda get-policy --function-name --query Policy` length | | `PublicPolicyException` | 400 | The policy would grant public access. Scope the principal, or add `aws:SourceAccount`/`aws:SourceArn`/organization conditions. | The principal and conditions in the statement you're adding | | `PreconditionFailedException` | 412 | The `RevisionId` you sent is stale: someone changed the policy. Re-read the policy and reapply. | `get-policy` → `RevisionId` vs the one you sent | | `ResourceConflictException` | 409 | `AddPermission` with a `StatementId` that already exists, or an update is in progress. | `get-policy`: is the `Sid` already there? | ## Deploy-time | Message | Fix | Check | |---|---|---| | `RequestEntityTooLargeException` on `create-function`/`update-function-code` | Zip over 50 MB for direct upload: upload to S3 and pass `S3Bucket`/`S3Key` (UNVERIFIED exception name). Unzipped over 250 MB, including layers: trim, or use a container image (10 GB). | `ls -l function.zip`; `unzip -l` total | | `CodeStorageExceededException` | Lambda-managed code storage (300 GB per Region) is full. Delete old versions, or use self-managed storage (`S3ObjectStorageMode=REFERENCE`, July 2026). UNVERIFIED exception name. | `aws lambda get-account-settings` → `AccountUsage.TotalCodeSize` vs `AccountLimit.TotalCodeSize` | | `InvalidParameterValueException: The runtime parameter of nodejs20.x is no longer supported…` | Runtime deprecated and creation blocked. Move to `nodejs24.x`. UNVERIFIED exact text. | The runtime's deprecation date in `reference/lambda/runtimes-and-limits.md` | ## When none of these fits Invoke once synchronously with `--log-type Tail` to get the last 4 KB of log, then query the full log group (`reference/cloudwatch/logs-insights-queries.md`). Split function errors (HTTP 200 + `FunctionError`) from service errors (exceptions). For service errors, search CloudTrail for the call's `errorCode`. Check the function's `State` and `LastUpdateStatusReason` with `aws lambda get-function-configuration`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.