I was helping a customer set up the AWS Landing Zone Accelerator last week when their CodePipeline suddenly failed at the Deploy stage. The error message was vague—just “Failed” in the console. After checking CloudWatch Logs and the CodeBuild execution, we found the issue was a missing CDK bootstrap in one of the member accounts. In this post, I’ll walk through exactly what causes LZA deployment failures and how to fix them.

The Problem

The LZA CodePipeline (aws-accelerator-pipeline) has multiple stages: Source → Build → Deploy → Account-specific stages. If the Deploy stage or any subsequent account/region stage fails, the entire pipeline stops. You see “Failed” status in the console, but the actual error is hidden in CloudWatch Logs.

Common error messages you might encounter:

Error Type Description
Missing bootstrap stack Stack:arn:aws:cloudformation does not exist
Permission denied User: arn:aws:iam is not authorized to perform
Malformed YAML Parse error in accounts-config.yaml or network-config.yaml
CodeBuild timeout Build step timed out after 480 minutes
Missing environment variable Variable is not defined in CodeBuild environment

Why Does This Happen?

The LZA is a TypeScript-based infrastructure as code solution that uses the AWS CDK. It orchestrates deployments across multiple accounts and regions. Several things can cause failures:

  • CDK bootstrap not run: The CDK requires a bootstrap CloudFormation stack in each target account and region. If this stack doesn’t exist, CDK deployment fails with a cryptic “Stack does not exist” error.
  • Insufficient IAM permissions: The Accelerator execution role needs permissions to assume AWSControlTowerExecution or OrganizationAccountAccessRole in member accounts. If this cross-account role doesn’t have the right trust relationship, deployments fail.
  • Conflicting resources: If target accounts already have CloudFormation stacks with the same logical IDs, VPCs with the same CIDR range, or Config recorders already running, CloudFormation drift occurs.
  • Malformed configuration files: The LZA reads multiple YAML files (accounts-config.yaml, network-config.yaml, security-config.yaml). A single typo in account ID, OU name, or region prevents the entire pipeline from building.
  • Missing CodeBuild environment variables: LZA CodeBuild projects expect specific variables like ACCELERATOR_REPOSITORY or account IDs. Missing variables cause the build to fail.

The Fix

Step 1: Check the Failed Stage

In the CodePipeline console, click the failed stage. You’ll see which action failed (e.g., “Deploy” or “us-east-1-123456789012”). Click the “Details” link:

aws codepipeline get-pipeline-state \
  --name aws-accelerator-pipeline \
  --region us-east-1

Step 2: Find the CloudWatch Logs

The CodeBuild project logs are in CloudWatch. Find the log group name:

aws logs describe-log-groups \
  --log-group-name-prefix /aws/codebuild/aws-accelerator \
  --region us-east-1

Stream the logs:

aws logs tail /aws/codebuild/aws-accelerator-build \
  --follow \
  --region us-east-1

Search for “ERROR” or “FAILED” to identify the root cause.

Step 3: Verify CDK Bootstrap

If you see “Stack does not exist”, the bootstrap stack is missing. Log into each target account/region and run:

# First, assume role into target account
aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/OrganizationAccountAccessRole \
  --role-session-name lza-bootstrap \
  --region us-east-1

# Then bootstrap the CDK
npx cdk bootstrap aws://123456789012/us-east-1 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess \
  --region us-east-1

Repeat for every target account and region listed in your accounts-config.yaml.

Step 4: Validate Configuration Files

Check your YAML syntax:

cd ~/aws-accelerator-config
npx ts-node validate-config.ts

Look for typos in:

  • Account IDs (must be 12 digits)
  • OU names (must match Organizations exactly)
  • Region names (must be valid AWS region codes like us-east-1)
  • CIDR ranges (must not conflict with existing VPCs)

Step 5: Retry the Pipeline

Once you’ve fixed the issue, restart the pipeline:

aws codepipeline start-pipeline-execution \
  --name aws-accelerator-pipeline \
  --region us-east-1

Monitor the execution:

aws codepipeline get-pipeline-execution \
  --pipeline-name aws-accelerator-pipeline \
  --pipeline-execution-id abc12345-1234-1234-1234-123456789012 \
  --region us-east-1

Is This Safe?

Retrying the pipeline is safe. The LZA uses CloudFormation StackSets with rollback enabled, so failed deployments automatically clean up. Just ensure you’ve fixed the underlying issue before retrying.

Key Takeaway

LZA deployment failures usually stem from missing CDK bootstrap stacks, permission issues, or malformed configuration files. Always check CloudWatch Logs first, validate your YAML configuration, and ensure CDK bootstrap is run in all target accounts before retrying.

Have questions or ran into a different LZA issue? Connect with me on LinkedIn or X.