Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

cdk synth says --app is required

Error--app is required either in command-line, in cdk.json or in ~/.cdk.json

Short answer

The CDK CLI needs a command that runs your app and finds it in three places: the --app option, cdk.json in the project folder, or cdk.json in your home folder. The message appears when you run cdk outside the project folder, or when cdk.json has no app entry.

  • Applies to AWS CDK CLI 2, TypeScript, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check that you are in the folder with cdk.json and that the file has an app entry.

    pwd
    cat cdk.json
  2. 2Match what you see, then jump to its fix

    1. 1cat cdk.json says the file does not existcdk is run outside the project directoryFix
    2. 2cat cdk.json shows no app keycdk.json exists but has no app entryFix
    3. 3A CI step or wrapper runs cdk from a different working directoryThe project cannot be entered, such as in a script or pipelineFix

What does the error look like?

  • --app is required either in command-line, in cdk.json or in ~/.cdk.json

Cause 1 of 3

cdk is run outside the project directory

1Check

The cdk.json created by cdk init holds the app command, and the CLI reads it from the folder you run it in.

ls cdk.json bin/

2Fix

Change into the project's main folder first, then run the command.

cd path/to/my-cdk-project
cdk synth

3Verify

The command now prints the synthesized template.

cdk synth

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

cdk.json exists but has no app entry

1Check

A hand-made or trimmed cdk.json must still contain the command that runs the app.

grep -n '"app"' cdk.json

2Fix

Add the app key. For a TypeScript project the default points at the file in bin/.

{
  "app": "npx ts-node bin/my-cdk-app.ts"
}

3Verify

List the stacks the app defines.

cdk ls

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

The project cannot be entered, such as in a script or pipeline

1Check

The CLI takes options from the command line first, then the project cdk.json, then ~/.cdk.json.

pwd && ls

2Fix

Pass the app command with -a, or put an app entry in the cdk.json in your home folder.

cdk synth --app "npx ts-node my-cdk-app.ts" MyStack

3Verify

The command runs without the message.

cdk ls --app "npx ts-node my-cdk-app.ts"

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Run cdk commands from the project root, and set the working directory in CI jobs.
  • Commit cdk.json to version control.
  • Do not delete the app key when tidying cdk.json.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

API Gateway gives up on a slow Lambda or Node.js backend

$context.integrationErrorMessage in the access log shows the integration error

API Gateway stops waiting for the backend at its integration timeout: 29 seconds by default on REST APIs, a fixed 30 seconds on HTTP APIs.

4 causes, each with a fix

Back end

The AWS SDK in Node.js cannot find any credentials

Missing credentials in config, if using AWS_CONFIG_FILE, set AWS_SDK_LOAD_CONFIG=1

The AWS SDK walks a fixed credential chain: code, environment variables, the shared files in ~/.aws, then role sources such as ECS or EC2.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.