Skip to content

Troubleshooting Guide

Jump to bottom
Cameron Pettit edited this page Sep 3, 2025 · 10 revisions

CDK

ENOSPC (No space left on device) while deploying

Problem

CDK runs inside a Docker container and spins up new images as cdk synth is used over and over. These images take up space on your device until your device is full

Solution

  1. Run docker system prune to wipe all unused Docker images from your device
  2. Run cdk synth and sam local start-api -t <template-name> WITHOUT the --skip-pull-image argument to rebuild the latest SAM Docker image.

Error: not enough values to unpack (expected 2, got 1)

Problem

On running cdk deploy, the error Error: not enough values to unpack (expected 2, got 1) is received and the stack fails to deploy.

Solution

This appears to happen when establishing websocket constructs in offline/local mode.

  1. Run export IS_OFFLINE=true to ensure you are running 'offline' locally.
  2. If you must run against a remote environment yet you want to test locally, you may have to look at the stack definition code and comment out wherever websocket constructs are defined. Make sure the comments are removed before pushing to the remote environment.
  3. If you are creating net new websocket constructs, ensure their definition code is wrapped in a check statement that ignores the websocket in the build phase if process.env.IS_OFFLINE=true.

CDK Synth/Deploy actions encounter problems with existing AWS resources

Problem

In some cases, particularly when an AWS resource is moved, renamed, or deleted, the cdk synth and cdk deploy actions may fail due to a previously existing resource.

Example: Api Gateway resource path variable was renamed, but the old one cannot be deleted.

Solution

  1. Go into CloudFormation
  2. Locate the resource causing the error
  3. Delete the resource manually
  4. Redeploy the stack - by re-running the GH Action, for example.

CDK should be smart enough to create a brand new resource with the correct settings.

CDK Deploy fails halfway through creating an API Gateway resource

Problem

When deleting an API Gateway resource, stack deploy fails on occasion such that an API Gateway resource at a particular path will have been created as per the stack in CloudFormation, but no resource exists. Usually when this happens, CloudFormation will list the path for the resource name it is expecting, for example /stage/resourcePath.

Solution

  1. Go into CloudFormation and collect the expected path for the resource, ie /stage/resourcePath.
  2. Go into API Gateway and manually recreate the resource /stage/resourcePath.
  3. Redeploy the stack - by re-running the GH Action, for example.
  4. If redeploy successful, go back into API Gateway and manually delete the resource /stage/resourcePath.

Local CDK API deployment - General errors

There are many places where deploying the API locally can trip up, so here is a general list of troubleshooting strategies that may help solve spurious errors:

  • Run cdk synth && sam local start-api -t <path/to/sam/template> with no other arguments at least once. Many of the yarn shorthand scripts that are included in package.json ignore certain steps that are cumbersome when developing locally, but still need to be run every so often. One example is the argument --skip-pull-image, which is included in yarn start, that tells the script to ignore looking for and downloading the latest SAM Docker image. If this image has not been downloaded previously (the local API has not been run before) or if it has been updated and is now out of date, spurious errors may arise.
  • Delete cdk.out and re-run cdk synth.

Local CDK API deployment: 'Failed to calculate the hash of resource <cdk.out/asset>'

Problem

When running yarn start and calling and endpoint, the server responds with 502 and the following error:

Failed to calculate the hash of resource <..user/path/reserve-rec-cdk/cdk.out/asset.xxx>

Solution

In the past it has been discovered that this error arises when a dependency is missing from asset.xxx. In particular, a dependency that was imported in the function code of a layer was not declared in the package.json file in the layer's nodejs folder. Navigating to the nodejs folder and adding the dependency resolved this particular issue.

cd layers/<layer>/nodejs && yarn add <dependency>

It is possible that similar missing reference errors or general compilation errors with the offending asset may cause similar problems.

The cause of this error is spurious but it can be circumvented by removing the --warm-containers LAZY/EAGER argument from sam local start-api (yarn start). This will force a container build every time the function is invoked (not ideal for heavy Lambda Layer use).

See the solutions for general local CDK API errors.

Clone this wiki locally