The Situation
It is a classic AWS frustration. You’ve tested your Lambda function in the console and it returns a perfect 200 OK. Everything looks ready. But the moment you trigger the API Gateway endpoint via Postman or your frontend, the request hits a wall with a 500 Internal Server Error.
When you check your API Gateway Execution Logs in CloudWatch, you find the culprit:
Execution failed due to configuration error: Invalid permissions on Lambda function
This error usually means API Gateway is knocking on the door, but Lambda won't let it in. Even if your Lambda has an IAM Role with AdministratorAccess, that only defines what the Lambda can do to other services. You are missing the Resource-based Policy, which defines who is allowed to trigger the Lambda in the first place.
How to Debug the Permission Gap
Before changing anything, verify if the policy exists. Run this command in your terminal:
aws lambda get-policy --function-name your-function-name
Look at the output. If you see a ResourceNotFoundException or if the Principal field is missing apigateway.amazonaws.com, the connection is blocked. API Gateway simply doesn't have the "Invite" to the party.
The Solution
Method 1: Using the AWS CLI (The Fastest Way)
You can manually grant the permission with one command. This is often the quickest fix for a broken dev environment. Replace the placeholders with your specific details, such as us-east-1 and your 12-digit AWS account ID:
aws lambda add-permission \
--function-name your-function-name \
--statement-id AllowAPIGatewayInvoke \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-east-1:123456789012:api-id/*/*/*"
The */*/* suffix is a wildcard. It allows any stage (like prod or dev), any HTTP method (GET, POST), and any resource path in that API to trigger your function.
Method 2: Using the AWS Console
- Open the Lambda Console and select your function.
- Navigate to the Configuration tab and select Permissions.
- Find the Resource-based policy statements section and click Add permissions.
- Choose AWS Service and select API Gateway from the dropdown.
- Assign a Statement ID (e.g.,
ProdApiAccess). - Set the Principal to
apigateway.amazonaws.com. - Restrict access by pasting your API Gateway ARN into the Source ARN field. This prevents other APIs in your account from accidentally triggering this function.
- Click Save.
Method 3: Infrastructure as Code (Terraform)
Manual fixes in the console are easily forgotten during the next deployment. If you use Terraform, ensure you include the aws_lambda_permission resource. This is the missing link that connects your API to your Lambda.
resource "aws_lambda_permission" "apigw_lambda" {
statement_id = "AllowExecutionFromAPIGateway"
action = "lambda:InvokeFunction"
function_name = aws_lambda_function.my_lambda.function_name
principal = "apigateway.amazonaws.com"
# This ARN allows any method on any path within the API
source_arn = "${aws_api_gateway_rest_api.my_api.execution_arn}/*/*"
}
Verification
After applying the fix, head back to the API Gateway console to test the integration:
- Select your API, then pick the specific Resource and Method.
- Click the Test tab (the lightning bolt icon).
- Press the Test button.
Success looks different now. Instead of a configuration error, your logs should show Endpoint response body before transformations followed by your actual Lambda output.
Lessons Learned
The AWS Console is deceptive. When you link a Lambda to an API Gateway manually, the UI often adds these permissions behind the scenes with a small popup confirmation. However, when you use the CLI, SAM, or Terraform, that "magic" doesn't happen. You are responsible for every link in the chain.
Struggling with YAML formatting while adding these permissions to a SAM template? I often use the YAML ↔ JSON Converter on ToolCraft to catch indentation errors. It’s faster than waiting five minutes for a CloudFormation stack to roll back because of a misplaced space.
The bottom line: IAM Roles control what the Lambda does. Resource-based policies control who can call it. Keep those two concepts separate, and you'll save hours of debugging.