🚨 CloudFormation Error: 'Resource handler returned message: ... (HandlerErrorCode: InvalidRequest)' — Cause, Fix, and Troubleshooting Guide

Overview

Resource handler returned message is the wrapper CloudFormation puts around an error that a resource provider (the “handler”) reported while creating, updating, or deleting a resource. Modern CloudFormation resource types run on the registry/handler framework, and when the underlying service API rejects the request, the handler surfaces the service’s message plus a normalized HandlerErrorCode and a RequestToken.

You will see it in the stack events and CLI output:

Resource handler returned message: "The security group 'sg-0123456789abcdef0' does not exist
in VPC 'vpc-0abc123'." (RequestToken: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111,
HandlerErrorCode: InvalidRequest)

This is not one specific bug — it is a generic envelope. The value is in learning to read it: the quoted message is the real cause (from the target service), HandlerErrorCode tells you the class of failure, and RequestToken lets you correlate with CloudTrail. Fix the quoted message and the error goes away.

Symptoms

• A CREATE_FAILED / UPDATE_FAILED event with Resource handler returned message: "...".
• A HandlerErrorCode such as InvalidRequest, AlreadyExists, AccessDenied, ResourceConflict, NotFound, or Throttling.
• The stack rolls back after the handler error.
• The quoted message names a specific downstream resource (a security group, IAM role, subnet, bucket, etc.).

aws cloudformation describe-stack-events --stack-name MyAppStack --region us-east-1

ResourceStatus: CREATE_FAILED
ResourceStatusReason: Resource handler returned message: "..." (HandlerErrorCode: InvalidRequest)

Common Root Causes

The HandlerErrorCode narrows things down fast:

1. InvalidRequest — the service rejected the parameters

Bad or inconsistent inputs: a referenced resource in the wrong VPC, an invalid enum value, a property combination the service does not allow.

"The security group ... does not exist in VPC ..." (HandlerErrorCode: InvalidRequest)

2. AccessDenied — the handler lacks IAM permission

CloudFormation (or the role passed to it) cannot call the underlying API.

"User: arn:aws:sts::123456789012:assumed-role/... is not authorized to perform: ec2:CreateTags"
(HandlerErrorCode: AccessDenied)

3. AlreadyExists / ResourceConflict — name or state collision

A fixed physical name is taken, or the resource is being modified concurrently.

"Table already exists: my-table" (HandlerErrorCode: AlreadyExists)

4. NotFound — a dependency does not exist

A referenced subnet, role, or parameter was deleted out-of-band or never created.

"Role arn:aws:iam::123456789012:role/app-role not found" (HandlerErrorCode: NotFound)

5. Throttling — API rate limits

Large stacks hammering a service API get throttled and the handler surfaces it.

"Rate exceeded" (HandlerErrorCode: Throttling)

6. GeneralServiceException / InternalFailure — downstream service error

A transient or service-side problem, often retryable.

How to Diagnose

Read the full event reason, untruncated

aws cloudformation describe-stack-events \
  --stack-name MyAppStack --region us-east-1 \
  --query "StackEvents[?ResourceStatus=='CREATE_FAILED'].[LogicalResourceId,ResourceStatusReason]" \
  --output text

The quoted string is the actual error — treat everything else as envelope.

Correlate the RequestToken in CloudTrail

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=ResourceName,AttributeValue=MyAppStack \
  --region us-east-1

Match the failing API call and its own error to see exactly which service rejected the request.

Identify the failing resource and its type

aws cloudformation describe-stack-resources \
  --stack-name MyAppStack --region us-east-1 \
  --query "StackResources[?ResourceStatus=='CREATE_FAILED']"

Reproduce the underlying API call

Once you know the service and parameters, call the API directly to get a cleaner message.

aws ec2 describe-security-groups --group-ids sg-0123456789abcdef0 --region us-east-1

Fixes

Fixes are dictated by the HandlerErrorCode:

InvalidRequest

Correct the offending property. In the VPC example, point the security group and the resource at the same VPC, or fix the referenced ID.

Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      SecurityGroupIds: [ !Ref AppSecurityGroup ]  # SG must be in the same VPC/subnet
      SubnetId: !Ref AppSubnet

AccessDenied

Grant the missing action to the deploying role (or the stack’s service role).

{ "Effect": "Allow", "Action": "ec2:CreateTags", "Resource": "*" }

AlreadyExists / ResourceConflict

Remove the hard-coded physical name (let CloudFormation generate one) or delete/import the orphaned resource.

NotFound

Recreate or correctly reference the missing dependency; add a DependsOn if it is an ordering issue.

Throttling

Add retries via DependsOn to serialize creation, reduce parallelism, or request a service quota increase.

    DependsOn: PreviousResource   # serialize to reduce concurrent API calls

What to Watch Out For

• Always read the quoted message first — the HandlerErrorCode is a category, not the cause.
• Keep the RequestToken; it is the fastest way to find the matching CloudTrail entry when the message is vague.
• InvalidRequest is frequently a cross-reference mismatch (VPC/subnet/AZ), not a syntax error in your template.
• A handler error triggers rollback; fix the root cause before retrying or you may hit UPDATE_ROLLBACK_FAILED.
• Transient Throttling/InternalFailure codes are often resolved by simply retrying the deploy.

Related Guides

• CloudFormation ‘CREATE_FAILED … already exists in stack’
• CloudFormation UPDATE_ROLLBACK_FAILED
• CloudFormation Circular Dependency Error