ERROR REFERENCE
Lambda could not use the KMS key for its environment variables
The error arrives wrapped in a Lambda
InvalidParameterValueException, so it reads like a bad
template value. It usually is not. The diagnosis is the
KMS Exception: buried inside it.
WHAT IT MEANS
What this error means
When a function sets KmsKeyArn, Lambda encrypts its
environment variables with that customer-managed key and needs a grant
on it at deploy time. If anything about the key blocks that, the whole
create or update fails:
CREATE_FAILED AWS::Lambda::Function Worker Lambda was unable to configure
access to your environment variables because the KMS key is invalid for
CreateGrant. Please check your KMS key settings. KMS Exception:
InvalidArnException (Service: Lambda, Error Code: InvalidParameterValueException)
Read the exception name after KMS Exception: before
changing anything. It splits three causes that look identical
in the wrapper and need completely different fixes:
AccessDeniedException— a key policy or grant problem. The deploying principal, Lambda service, or function execution role cannot use the key through the required grant path. This is the one people misdiagnose as an IAM problem: a KMS key has its own resource policy, and an identity policy alone does not grant access to it.DisabledExceptionorKMSInvalidStateException— a key state problem. The key is disabled or pending deletion. No policy change helps; the key has to be enabled or the deletion cancelled.InvalidArnExceptionorNotFoundException— a wrong key. The ARN is malformed, or names another Region or account. A Lambda function can only use a key in its own Region.
The message The ciphertext refers to a customer master key that
does not exist, does not exist in this region, or you are not allowed
to access is the same family — and note it deliberately does not
tell you which of the three it was, so the checks below are the way to
find out.
FIX
How to fix it
-
Confirm the key exists and check its state, in the
function's own Region:
Readaws kms describe-key --key-id <key-arn>KeyStatein the output.DisabledorPendingDeletionexplains the failure by itself. -
Review the key policy, not just IAM identity policies.
Check the key policy and grants for both the deploying principal and
the function's execution role. Confirm
kms:CreateGrant,kms:Encryptandkms:DescribeKeyfor the deployment and Lambda grant path, pluskms:Decryptwherever the execution role actually decrypts values. A KMS key is one of the resources where the resource policy is authoritative. -
Check the Region and account in the ARN. If it is
malformed or points elsewhere, fix
KmsKeyArnin the template — no permission change makes a cross-Region key work. - For a key owned by another account, confirm the key policy in the owning account grants the deploying principal, and check whether an existing grant constrains the operation.
-
Re-save or re-encrypt the environment configuration, then
re-run the deployment once
describe-keyshows an enabled key in the right Region and the policy permits the grant.
AUTOMATE THE TRIAGE
Diagnose this automatically
SAM Doctor reads the KMS exception out of the Lambda wrapper (high confidence) and reports the key checks instead of routing you to the IAM policy simulator, which is where the generic denial finding would have sent you. Runs locally; no AWS access, no log upload.
python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdownRELATED
Related errors
- AWS denied an API action required by the deployment — the generic denial this used to be misfiled as.
- Lambda does not have permission to access the ECR image — the other resource-policy failure that reads like an IAM one.
- CloudFormation resource creation or update failed — the wrapper event this appears inside.