opensite-ai/opensite-skills / aws-cdk
aws-cdk
UnverifiedAuthors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
| File | Kind | Size |
|---|---|---|
| .aws-skill-metadata | other | 18 B |
| SKILL.md | skill md | 8.7 KB |
| references/bootstrap-and-project-setup.md | markdown | 8.0 KB |
| references/compliance-and-drift.md | markdown | 5.2 KB |
| references/construct-patterns.md | markdown | 10.4 KB |
| references/fast-deployments.md | markdown | 13.4 KB |
| references/import-and-migrate.md | markdown | 6.3 KB |
| references/refactor-and-prevent-replacement.md | markdown | 6.2 KB |
| references/troubleshooting-credentials.md | markdown | 5.8 KB |
| references/troubleshooting-deployment.md | markdown | 12.9 KB |
| references/troubleshooting-synth.md | markdown | 8.8 KB |
| references/v1-to-v2-migration.md | markdown | 3.2 KB |
references/troubleshooting-credentials.md
View on GitHub# Troubleshooting: Credentials and Environment
## Table of Contents
- [Troubleshooting: Credentials and Environment](#troubleshooting-credentials-and-environment)
- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [NoCredentials / ExpiredToken / AssumeRoleFailed](#nocredentials--expiredtoken--assumerolefailed)
- [Error variants](#error-variants)
- [Diagnosis](#diagnosis)
- [Common causes and fixes](#common-causes-and-fixes)
- [Bootstrap Version Validation](#bootstrap-version-validation)
- [Error variants](#error-variants-1)
- [Fixes](#fixes)
- [Unresolved Account](#unresolved-account)
- [Fix — set explicit environment](#fix--set-explicit-environment)
- [Fix — commit context](#fix--commit-context)
- [Alternatives to context providers](#alternatives-to-context-providers)
- [Account/Region Tokens](#accountregion-tokens)
- [Problem](#problem)
- [Fix](#fix)
---
## Overview
This reference covers authentication, authorization, and environment-resolution errors. These failures occur when the CDK CLI cannot determine who you are, what account/region to target, or whether the bootstrap stack is compatible.
---
## NoCredentials / ExpiredToken / AssumeRoleFailed
### Error variants
| Error | Meaning |
| ------------------------ | -------------------------------------------------------------- |
| `NoCredentials` | No AWS credentials found in the environment |
| `ExpiredToken` | Credentials exist but the session has expired |
| `AssumeRoleFailed` | CLI found credentials but cannot assume the CDK bootstrap role |
| `AssumeRoleExpiredToken` | Token expired during a role assumption chain |
### Diagnosis
You MUST run these commands first:
```bash
aws sts get-caller-identity
cdk doctor
```
If `get-caller-identity` fails, the problem is with your base credentials, not CDK.
### Common causes and fixes
**No CLI credentials configured:**
You MUST configure credentials via one of: `~/.aws/credentials`, environment variables (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`), or SSO.
**Wrong profile:**
```bash
cdk deploy $STACK --profile $PROFILE
```
Or set the environment variable:
```bash
export AWS_PROFILE=$PROFILE
```
**Expired SSO session:**
```bash
aws sso login --profile $PROFILE
```
**Missing `sts:AssumeRole` on bootstrap roles:**
The CDK CLI assumes roles created by `cdk bootstrap`. If the calling principal lacks `sts:AssumeRole` permission on those roles, deployment fails. You MUST verify the trust policy on the bootstrap roles allows your identity.
---
## Bootstrap Version Validation
### Error variants
- `BootstrapVersionValidation` — the deployed bootstrap stack version is too old for the constructs being deployed.
- `SSM parameter /cdk-bootstrap/$QUALIFIER/version not found` — the bootstrap stack does not exist in the target account/region, or the qualifier does not match.
- `Cloud assembly schema version mismatch` — the CLI version is incompatible with the cloud assembly produced by the CDK library.
### Fixes
**Re-bootstrap the target environment:**
```bash
cdk bootstrap aws://$ACCOUNT/$REGION
```
**Match the qualifier** if you use a custom one:
```bash
cdk bootstrap aws://$ACCOUNT/$REGION --qualifier $QUALIFIER
```
**Grant SSM read access:**
The CDK CLI reads the bootstrap version from SSM Parameter Store. The deploying role MUST have `ssm:GetParameter` permission on `/cdk-bootstrap/$QUALIFIER/version`.
**CLI version mismatch:**
You SHOULD pin `aws-cdk` as a dev dependency to keep the CLI version aligned with the library:
```bash
npm install --save-dev aws-cdk@$VERSION
npx cdk deploy $STACK
```
This prevents drift between the globally installed CLI and the library version used in your project.
---
## Unresolved Account
```
Cannot determine account/region; context providers need concrete values
```
Context providers (e.g., `Vpc.fromLookup`) make API calls at synth time and MUST know the target account and region. Env-agnostic stacks (no explicit `env`) cannot use context providers.
### Fix — set explicit environment
```typescript
new MyStack(app, 'MyStack', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION,
},
});
```
`CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` are set automatically by the CDK CLI from your current credentials.
### Fix — commit context
You MUST commit `cdk.context.json` to version control. This file caches the results of context provider lookups so that synth is reproducible without live API calls.
### Alternatives to context providers
If you cannot set an explicit environment, you SHOULD use one of:
- `ec2.Vpc.fromVpcAttributes()` — provide VPC ID, AZs, and subnet IDs directly.
- SSM Parameter Store lookups at deploy time — store infrastructure values in SSM and read them with `ssm.StringParameter.valueForStringParameter()`.
---
## Account/Region Tokens
`stack.account` and `stack.region` return **Tokens** (lazy placeholders), not real values, when the stack is env-agnostic.
### Problem
```typescript
if (stack.region === 'us-east-1') {
// This NEVER matches — stack.region is a Token string like ${Token[AWS.Region.1234]}
}
```
Tokens are resolved by CloudFormation at deploy time, not at synth time. You MUST NOT use them in synth-time conditional logic.
### Fix
Set an explicit environment on the stack so that `stack.account` and `stack.region` resolve to real values at synth time:
```typescript
new MyStack(app, 'MyStack', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: 'us-east-1',
},
});
```
With an explicit env, synth-time conditionals work as expected. Without it, you MUST use `CfnCondition` for deploy-time branching instead of TypeScript `if` statements.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |