What it means
A Lambda function has a lifecycle state, and it is not usable until that state is Active. For a plain function the Pending window is short enough that nobody notices. For a VPC-attached function it is long enough to break scripts that assume creation is instantaneous.
The reason is elastic network interfaces. Attaching a function to a VPC requires Lambda to provision shared ENIs for that combination of subnets and security groups, and that is substantially slower than anything else in function creation. Until it completes, the function exists, reports Pending, and refuses both invocations and updates.
The distinction worth drawing early is between Pending because it is working and Pending because it cannot finish. State reads the same for both. StateReason and StateReasonCode do not — and the second case, where the execution role lacks ec2:CreateNetworkInterface or the subnets have no free addresses, will never resolve however long you wait. Reading the reason field first saves the twenty minutes otherwise spent finding that out.
Most reports of this being "stuck" are really a deployment script assuming a create call is synchronous. It returns as soon as Lambda accepts the request, not when the function is ready, so the next call in the pipeline arrives during the window and is rejected. aws lambda wait function-active-v2 blocks on the actual state, which is both more reliable than a fixed sleep and faster, since a plain function clears in a moment while a VPC one takes as long as it takes.
Nothing about this reaches CloudWatch Logs. The function has never run, so it has written nothing — the entire failure lives in the API response and in the function's configuration.
Where you'll see it
Deployment output
Not in CloudWatchThis failure happens before the function runs, so nothing about it reaches CloudWatch Logs — there is no invocation, and no log group entry to find. Once the deployment succeeds and the function starts running, the rest of this index covers what you will see there.
Causes, most likely first
The function is VPC-attached and ENIs are being provisioned
Check whether the function has a VpcConfig. Creating the shared network interfaces for a new subnet-and-security-group combination is much slower than creating a plain function, and it is the reason nearly every long Pending state happens.
The subnets have no free IP addresses
Check AvailableIpAddressCount on each configured subnet. When there is no address to give an interface, provisioning cannot complete, and the function stays Pending until it fails rather than failing immediately.
The execution role lacks the EC2 permissions
Read StateReason rather than only State. A role without ec2:CreateNetworkInterface cannot complete provisioning, and the reason field names the problem where the state alone does not.
A deployment script issues its next call immediately
Look at whether the pipeline creates and then updates without waiting. This is not really the function being stuck — it is a script assuming creation is synchronous, which for a VPC function it emphatically is not.
Fixes
Wait for the function to become active rather than guessing at a delay
The CLI has a waiter for exactly this. It is more reliable than a fixed sleep, which is always either too short for a VPC function or wasted time for a plain one.
bashaws lambda create-function --function-name orders-fn ...
# Blocks until State leaves Pending.
aws lambda wait function-active-v2 --function-name orders-fn
aws lambda update-function-configuration --function-name orders-fn --timeout 60
Read StateReason before assuming it is only slow
Pending because provisioning is in progress and Pending because provisioning cannot succeed look identical in State. The reason fields distinguish them, and one of them will never resolve on its own.
bashaws lambda get-function-configuration --function-name orders-fn \
--query '{State:State,Reason:StateReason,Code:StateReasonCode,Vpc:VpcConfig}'
Give the function's role the VPC access policy up front
Attaching AWSLambdaVPCAccessExecutionRole before creating a VPC-attached function avoids the version of this that never completes.
yamlManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole
Let CloudFormation do the waiting
A stack update waits for each resource to stabilise before continuing, so a deployment expressed as CloudFormation or SAM does not hit this. Most occurrences come from scripts issuing raw API calls back to back.
Also seen as
The same underlying failure, worded differently by a different runtime, SDK version, or logging layer. All of these land here — there is no separate page for each phrasing.
Related errors
Errors that show up alongside this one, or that people mistake for it.
References
- AWS Lambda Developer Guide — Lambda function states
- AWS Lambda Developer Guide — Troubleshoot invocation issues
This one happens before there are any logs.
LogStitch reads CloudWatch, and a deployment that fails never writes to it — so this is not an error it can find for you. Once the function deploys and starts running, the free web stitcher groups its invocations in your browser, and the Mac app does the same across every function in your account.