View a markdown version of this page

Troubleshooting - AWS CDK Blocks

Troubleshooting

Local development issues

Port 3000 or 3001 already in use

Symptom: Another program uses port 3000 or 3001, or a process on that port stops after you run npm run dev.

npm run dev frees its ports when it starts. It stops whatever process listens on its API port (3000, or 3001 for templates without a frontend) and on its frontend port (3100). It sends SIGTERM, then SIGKILL if the port is still held, and prints Reclaimed port <n>. This happens whatever the process is, so a different app on one of those ports is stopped too. Only a running AWS CDK Blocks dev server for the same project is left alone: a second npm run dev exits and tells you to run npm run dev:stop first.

Solution: To keep another program on those ports, run the dev server on different ports. --port sets the API port, and --frontend-port sets the frontend port:

npm run dev -- --port 3002 --frontend-port 3102

To stop a dev server on a port other than the default, pass the port to npm run dev:stop:

npm run dev:stop -- --port 3002

Local data is stale or corrupted

Symptom: Local development behaves unexpectedly, returns old data, or throws deserialization errors.

Solution: Delete the .bb-data/ directory to reset all local state:

rm -rf .bb-data npm run dev

TypeScript errors after changing the backend

Symptom: Frontend shows type errors after modifying API methods in cdk-blocks/index.ts.

Solution: This is expected. This means type safety is working. Update your frontend code to match the new API signature. If your IDE doesn’t pick up the changes, restart the TypeScript language server.

Deployment issues

CDK bootstrap required

Symptom: npm run deploy or npm run sandbox stops before it synthesizes, with a message such as "CDK is not bootstrapped in Region REGION of account ACCOUNT_ID, so npm run deploy cannot deploy there."

Solution: Run the bootstrap command that the message prints, from your project directory:

npx cdk bootstrap aws://ACCOUNT_ID/REGION --app=

You need to do this only one time per account/Region combination. If your app has a support stack in us-east-1, bootstrap us-east-1 too. The check that runs before a deploy does not cover it, so a deploy that reaches that stack can still fail with an error such as "SSM parameter /cdk-bootstrap/hnb659fds/version not found." For more information, see Bootstrap the AWS CDK.

AWS credentials expired or missing

Symptom: Deployment fails with ExpiredTokenException or "Unable to locate credentials."

Solution: Refresh your AWS credentials:

# If using IAM Identity Center aws sso login # Verify credentials work aws sts get-caller-identity

Sandbox deployment hangs or times out

Symptom: npm run sandbox takes more than a few minutes or appears stuck.

Solution: The first sandbox deploy is a full CloudFormation deployment and can take several minutes. If it fails, the sandbox usually leaves the stack in a failed state, because automatic rollback is off, and the next npm run sandbox cannot update it. Destroy and recreate:

npm run sandbox:destroy npm run sandbox

sandbox:destroy handles a stack in ROLLBACK_COMPLETE. If it reports UPDATE_ROLLBACK_FAILED, first run aws cloudformation continue-update-rollback --stack-name <your-sandbox-stack>. To see the stack and its events, run npm run sandbox:console. It opens the CloudFormation stack list filtered to the first stack in .cdk-blocks-sandbox/outputs.json, which your most recent npm run sandbox or npm run deploy wrote. It takes the Region from AWS_REGION, AWS_DEFAULT_REGION, or your AWS CLI configuration, not from cdk.json, so check that it opened the Region your stack is in.

Permission denied during deployment

Symptom: Deployment fails with AccessDenied or "User is not authorized to perform" errors.

Solution: Your IAM user or role needs permissions to create Lambda functions, DynamoDB tables, API Gateway APIs, IAM roles, and CloudFormation stacks. Use an account with AdministratorAccess for initial setup, then scope down for CI/CD.

Runtime issues

Behavior differs between local and deployed

Symptom: Code works locally but fails in production, or vice versa.

Common causes:

Cause Solution

A KVStore indexed field set to null

DynamoDB rejects the write on AWS, and the local implementation accepts it. To keep an item out of an index, leave the field out

DynamoDB query pagination

Handle paginated responses. Local implementations return all results in a single response

Aurora connection limits

Reduce concurrent connections or configure connection pooling

Lambda cold starts

First request after idle period is slower. Not a bug

Configuration or environment variables missing

Use the AppSetting Block for runtime configuration and the Secret Block for secrets. For more information, see Configuration. To pass a value from your CDK code, such as a resource ARN, call registerConfig(stack, 'KEY', value) from aws-cdk-blocks/cdk. Every function then reads it as process.env.KEY.

API returns 500 Internal Server Error

Symptom: Frontend receives a generic 500 error without a useful message.

Solution: Unhandled exceptions from your own code return as 500s with the message "Internal error" and no name (to avoid leaking internals). Named errors that CDK Blocks throw, such as ValidationFailedException, keep their name and message. AWS SDK errors that pass through a CDK Block also return as "Internal error". To send an error the client can see, throw new ApiError(message, status, { name }). To see the full error and stack trace, check CloudWatch Logs for the Lambda function.

The handler’s log group has a name that CloudFormation generates, not /aws/lambda/…​. Find it in your stack’s resources, then tail it. Your stack name is <stackId>-prod for npm run deploy, or <stackId>-<sandboxId> for a sandbox. It is also a top-level key in .cdk-blocks-sandbox/outputs.json after your most recent deploy.

aws cloudformation list-stack-resources --stack-name <stack-name> \ --query "StackResourceSummaries[?contains(LogicalResourceId, 'HandlerLogGroup')].PhysicalResourceId" \ --output text aws logs tail <log-group-name> --follow

You can also run npm run sandbox:console, check that it opened the Region your stack is in, choose your stack in the filtered list, and choose the log group on the Resources tab.

Getting further help

If your issue isn’t covered here:

  • Check CDK Blocks GitHub Issues for known bugs and workarounds

  • File a new issue with your error message, Node.js version, and steps to reproduce