aws-cdk import: --role-arn is also parsed as --record-resource-mapping, creating a mapping file path from ARN

[yutaro1985]

Describe the bug

When running cdk import with --role-arn, the CLI incorrectly also sets --record-resource-mapping to the same value.

As a result, the ARN string is treated as a file path, and a file/directory like this is created locally:

arn:aws:iam::<ACCOUNT_ID>:role/<CLOUDFORMATION_EXECUTION_ROLE_NAME>

CLI output includes:

arn:aws:iam::<ACCOUNT_ID>:role/<CLOUDFORMATION_EXECUTION_ROLE_NAME>: mapping file written.

This makes cdk import unusable when we must explicitly specify an execution role.

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

--role-arn should only set the CloudFormation execution role for import/deploy operations.

It should not set record-resource-mapping, and should not create a local mapping file path from the ARN string.

Current Behavior

Both values are set internally from a single flag.

With -vvv, CLI arguments include both:

• roleArn: arn:aws:iam::...:role/...
• recordResourceMapping: arn:aws:iam::...:role/...

Reproduction Steps

1. Use local CDK CLI (example: pnpm exec cdk, not global).
2. Run:

cd infra/cdk
CDK_DEFAULT_ACCOUNT=<ACCOUNT_ID> \
CDK_DEFAULT_REGION=<AWS_REGION> \
pnpm exec cdk import <STACK_NAME> \
  -c env=<ENV_NAME> \
  --role-arn=arn:aws:iam::<ACCOUNT_ID>:role/<CLOUDFORMATION_EXECUTION_ROLE_NAME> \
  -vvv

3. Observe debug output: record-resource-mapping is set to the same ARN.
4. Observe local file/directory creation from the ARN path and output mapping file written.

Possible Solution

cdk import appears to have conflicting short option binding (-r) for both:

• --role-arn
• --record-resource-mapping

Please separate these options (remove alias conflict and ensure independent parsing).

Possible Solution

No response

Additional Information/Context

cdk import --help currently shows both options using -r, which appears to be the root cause.

AWS CDK Library version (aws-cdk-lib)

2.236.0

AWS CDK CLI version

2.1106.1 (build 4e0d9f7)

Node.js Version

v22.18.0

OS

Amazon Linux 2023 (Cloud9/EC2 environment)

Language

Python

Language Version

Python 3.11

Other information

We can work around by not using --role-arn, but in our environment explicit execution role is required, so this is blocking for cdk import.

[pahud]

Hi @yutaro1985,

This is a good catch — thanks for the detailed write-up.

From my view, the root cause is exactly what you identified: a short-alias collision on -r. The global --role-arn option and the import-specific --record-resource-mapping option both declare alias: 'r' in cli-config.ts. When yargs sees the -r alias on both a global and a subcommand option, it appears to assign the value to both — which is why recordResourceMapping ends up with the ARN string and the CLI tries to write it as a file path.

Problem at a Glance:

  cdk import MyStack --role-arn=arn:aws:iam::123:role/MyRole
                           │
                    yargs resolves -r
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
   ┌──────────────────┐     ┌───────────────────────────┐
   │  --role-arn       │     │  --record-resource-mapping │
   │  alias: -r        │     │  alias: -r                 │
   │  (global)         │     │  (import subcommand)       │
   └────────┬─────────┘     └─────────────┬─────────────┘
            ▼                             ▼
   roleArn = "arn:..."         recordResourceMapping = "arn:..."
                                          │
                                          ▼
                               ┌─────────────────────┐
                               │ ARN treated as file  │
                               │ path ▶ bogus file    │
                               └─────────────────────┘

It appears the fix would be to remove (or change) the -r alias on --record-resource-mapping in the import command definition inside cli-config.ts, since the global --role-arn has a more established claim to -r. The relevant code lives in the aws/aws-cdk-cli repository:

• Source of truth: packages/aws-cdk/lib/cli/cli-config.ts (the record-resource-mapping entry under commands.import.options)
• Generated parser: packages/aws-cdk/lib/cli/parse-command-line-arguments.ts (auto-generated from the config)

As a workaround until this is fixed, you could use the long-form --role-arn together with explicitly not passing -r, though from your description it sounds like even --role-arn triggers the collision (since yargs maps it back through the alias internally). In that case, setting the role via the CDK_DEFAULT_ACCOUNT / bootstrap trust relationship rather than --role-arn might be the only workaround for now.

8. Reproduction

Reproduced: ✅ YES (CDK CLI 2.1101.0, yargs alias collision confirmed)

The bug was reproduced using a minimal yargs script that mirrors the exact CDK CLI option configuration from cli-config.ts. No AWS credentials or working CDK app are needed — the bug is purely in the argument parsing layer.

Reproduction command (buggy):

node repro-37044/repro.js import MyStack --role-arn=arn:aws:iam::123456789012:role/MyRole

Output:

=== Parsed arguments ===
roleArn: "arn:aws:iam::123456789012:role/MyRole"
recordResourceMapping: "arn:aws:iam::123456789012:role/MyRole"

BUG REPRODUCED: YES — recordResourceMapping got the ARN value (should be undefined)

Both --role-arn=<value> and -r <value> trigger the collision — yargs assigns the value to both options because they share the -r alias.

Fix verified: Removing alias: 'r' from record-resource-mapping resolves the issue:

node repro-37044/repro-fixed.js import MyStack --role-arn=arn:aws:iam::123456789012:role/MyRole

=== Parsed arguments ===
roleArn: "arn:aws:iam::123456789012:role/MyRole"
recordResourceMapping: undefined

BUG REPRODUCED: NO — recordResourceMapping is correctly undefined

Reproduction files: repro-37044/repro.js (buggy), repro-37044/repro-fixed.js (fixed)