fix(agentcore): fresh-account Runtime create fails with misleading ServiceLimitExceeded when the AgentCore service-linked role is rate-limited

[vivibui]

Component: cdk (AgentCore runtime) / docs

Describe the bug

On a fresh account, the first deploy can fail creating AWS::BedrockAgentCore::Runtime with a message that reads like a service quota problem but is not:

Resource handler returned message: "Limit exceeded for resource of type
'AWS::BedrockAgentCore::Runtime'. Reason: Failed creating service linked role.
Rate limit exceeded from IAM (Service: BedrockAgentCoreControl, Status Code: 402,
Request ID: ...)" (HandlerErrorCode: ServiceLimitExceeded)

AgentCore is auto-creating its service-linked role (AWSServiceRoleForBedrockAgentCoreGatewayNetwork) on first use and the IAM call is rate-limited. ServiceLimitExceeded plus "Limit exceeded" sends you looking at Service Quotas, where there is nothing to find.

The failure also cascades: the Runtime failure cancels sibling resources mid-create, which is how #866 was found. So one transient IAM rate limit produced a rolled-back stack that then could not be deleted without --retain-resources surgery.

Expected behavior

A fresh-account deploy either provisions the service-linked role deterministically, or fails with a message that names the actual cause and the one-line remedy.

Current behavior

Deploy fails at the Runtime with ServiceLimitExceeded, rolls back, and the operator has no indication that a service-linked role is involved.

Reproduction steps

1. Fresh AWS account with no AWSServiceRoleForBedrockAgentCoreGatewayNetwork — confirm with:

   aws iam list-roles --path-prefix /aws-service-role/bedrock-agentcore.amazonaws.com/

   (empty)
2. mise //cdk:bootstrap && mise //cdk:deploy -- --require-approval never
3. Observe the Runtime CREATE_FAILED above.

Pre-creating the role fixes it permanently — the next deploy succeeded first try, 100 resources, Runtime READY:

aws iam create-service-linked-role --aws-service-name bedrock-agentcore.amazonaws.com

Possible solution

Either or both:

1. Declare the dependency in the stack. An AWS::IAM::ServiceLinkedRole for bedrock-agentcore.amazonaws.com that the Runtime depends on, so CloudFormation orders and retries it instead of relying on an implicit first-use side effect. Worth checking whether CFN tolerates the role already existing — an account that has used AgentCore before will already have it, and AWS::IAM::ServiceLinkedRole fails rather than adopting a pre-existing role, so this likely needs a custom resource or a documented context flag.
2. Document it as a QUICK_START troubleshooting row. Cheap, and useful even with option 1, since the misleading error will keep appearing in older stacks and other regions.

Option 2 is already covered by #868, which adds the row while fixing the rollback wedge. Filing this so option 1 is tracked separately rather than lost in a PR description.

Environment

• Node v22.23.2 (mise) · mise 2026.7.0 macos-arm64 · Region us-east-1
• Commit 12c9b63f
• Related: #866 (the rollback wedge this triggered), #868 (docs row)