Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/okruti-raghuraj/aws-1/llms.txt

Use this file to discover all available pages before exploring further.

Working with CDK Pipelines introduces a layer of complexity beyond a standard CDK stack: the pipeline provisions itself, mutates on every push, and spans multiple AWS services (CodePipeline, CodeBuild, S3, KMS, and optionally cross-account roles). Most issues fall into a small set of repeatable patterns. The sections below cover the errors developers encounter most frequently, their root causes, and the exact steps to resolve them.

​
Common issues

Cause: CDK Pipelines uses S3 buckets and (optionally) ECR repositories to stage assets during synthesis. These resources are created by the CDK bootstrap process, which must be run once per AWS account/region combination before any pipeline deployment can succeed.Fix: Run the bootstrap command, substituting your real account ID and target region:
cdk bootstrap aws://ACCOUNT_ID/REGION
For example:
cdk bootstrap aws://123456789012/us-east-1
After bootstrap completes you will see a CDKToolkit CloudFormation stack in your account. Re-run cdk deploy once that stack reaches CREATE_COMPLETE.
Cause: CodePipelineSource.gitHub(...) relies on an AWS CodeStar Connection to authenticate with GitHub. Connections are created in a PENDING state and must be manually authorized in the AWS Console before any pipeline run can clone your repository.Fix:
1

Open the AWS Console

Navigate to AWS Console → Developer Tools → Settings → Connections (or search for “CodeStar Connections”).
2

Find the pending connection

Locate the connection that was automatically created when you first deployed the stack. Its status will show Pending.
3

Authorize the connection

Click Update pending connection, then follow the OAuth prompts to grant AWS access to your GitHub account or organization.
4

Re-run the pipeline

Once the connection status changes to Available, trigger a new pipeline execution. The source stage should now clone successfully.
Cause: The Synth stage runs npm ci, npm run build, and npx cdk synth inside a CodeBuild environment. If any of those commands fail — most commonly because of a TypeScript compilation error introduced in a recent commit — the entire pipeline stops at this stage.Fix: Reproduce the failure locally before pushing:
npm ci
npm run build
npx cdk synth
TypeScript errors will surface during npm run build (tsc). Fix all reported errors, confirm cdk synth produces output without warnings, then push the corrected commit. The pipeline will re-trigger automatically and the Synth stage will pass.
Cause: CDK Pipelines requires an explicit environment (account + region) on the pipeline stack. In the generated bin/aws-cdk-pipeline.ts entry point the env block is commented out by default:
// env: { account: '123456789012', region: 'us-east-1' }
Without it, CDK cannot resolve which account and region to target.Fix: Open bin/aws-cdk-pipeline.ts and uncomment the env property, replacing the placeholder values with your real account ID and region:
new AwsCdkPipelineStack(app, 'AwsCdkPipelineStack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region:  process.env.CDK_DEFAULT_REGION,
  },
});
If you prefer hard-coded values (useful in CI environments without the CDK CLI configured):
env: { account: '123456789012', region: 'us-east-1' }
Ensure CDK_DEFAULT_ACCOUNT and CDK_DEFAULT_REGION are exported in your shell session when using the environment-variable form.
Cause: The pipeline stack sets crossAccountKeys: false in the CodePipeline constructor:
const pipeline = new CodePipeline(this, 'Pipeline', {
  pipelineName: 'TestPipeline',
  crossAccountKeys: false,
  // ...
});
This setting disables KMS customer-managed key creation for the artifact bucket, which reduces cost and permissions overhead. However, if you later try to deploy an application stage to a different AWS account, CodePipeline cannot decrypt the artifacts in the source account’s S3 bucket and the cross-account deployment fails.Fix: Set crossAccountKeys: true before adding any cross-account stage:
const pipeline = new CodePipeline(this, 'Pipeline', {
  pipelineName: 'TestPipeline',
  crossAccountKeys: true,
  // ...
});
Then ensure the target account’s deployment role has been granted permission to use the KMS key (CDK handles this automatically when both stacks are deployed with CDK Pipelines). Re-deploy the pipeline stack after making this change.
Cause: The source-map-support package (listed under dependencies in package.json) is not present in node_modules. This happens when npm install has not been run, or when node_modules was deleted or excluded from the working directory.Fix: Run npm install from inside the aws-cdk-pipeline/ directory:
cd aws-cdk-pipeline
npm install
Verify the package is installed:
ls node_modules/source-map-support
If you are running inside CodeBuild and see this error in the Synth stage, confirm that the commands list includes npm ci as the first step — it is already present in the default configuration:
commands: ['npm ci', 'npm run build', 'npx cdk synth']
Cause: The AwsCdkPipelineStack in lib/aws-cdk-pipeline-stack.ts only defines the pipeline infrastructure. Application stages (the actual workloads) must be added to the pipeline explicitly with pipeline.addStage(). The scaffolded code leaves MyPipelineAppStage commented out, so only the pipeline itself is ever updated — your application changes are never deployed.Fix: Define your application stage and add it to the pipeline. Using the pattern from the CDK Pipelines documentation:
import { MyPipelineAppStage } from './my-pipeline-app-stage';

// After pipeline construction:
pipeline.addStage(new MyPipelineAppStage(this, 'Prod', {
  env: { account: '123456789012', region: 'us-east-1' }
}));
Create lib/my-pipeline-app-stage.ts as a cdk.Stage subclass that instantiates your application stacks. Push the change — the pipeline will self-mutate to include the new stage on its next run, then immediately execute it.

​
Useful debugging commands

The following commands help you inspect and manage the pipeline stack without navigating the AWS Console: 
# View synthesized CloudFormation template
cdk synth

# Compare stack with deployed state
cdk diff

# View stack events in real-time
aws cloudformation describe-stack-events --stack-name AwsCdkPipelineStack

# List all CDK stacks
cdk list

# Destroy the pipeline stack
cdk destroy AwsCdkPipelineStack
cdk synth is especially useful during troubleshooting: if synthesis fails locally you will see the exact TypeScript or CDK error before it reaches CodeBuild. cdk diff shows property-level changes between your local code and what is currently deployed, which helps confirm that a fix will actually change the intended resource.
cdk destroy AwsCdkPipelineStack permanently deletes the CodePipeline, the CodeBuild projects, the artifact S3 bucket, and all other resources created by the pipeline stack itself. It does not delete the resources deployed by your application stages (e.g. Lambda functions, DynamoDB tables, or additional stacks). Destroy those stages explicitly before destroying the pipeline if you want a clean teardown.

Build docs developers (and LLMs) love

Get started for freeTalk to us