failed bootstrapping: Error: CDK the stack named CDKToolkit failed creation

When running Bootstrap with AWS CDK, I encountered the error failed bootstrapping: Error: The stack named <name>-CDKToolkit failed creation, it may need to be manually deleted from the AWS console: ROLLBACK_COMPLETE. Here are my notes on how to handle it.

The console error message alone didn’t tell me the cause, so I checked CloudFormation for more details.

Export with name CdkBootstrap-hnb659fds-FileAssetKeyArn is already exported by stack <name>-CDKToolkit. Rollback requested by user.

From the error, it seems to say “It’s already created, so can’t create it again.”

However, I don’t remember creating it, and checking CloudFormation, there was no trace of this CDK stack. What could be the cause? I had previously succeeded with Bootstrap using this method.

In conclusion, the cause was a previously created CDK stack.

Before this error, Bootstrap worked fine, and then this error occurred in the same region. It seems likely, but the stack names are different, so I spent a lot of time confused.

So, the details:

When you run Bootstrap or deploy with CDK by default, a random string called qualifier is used internally as a resource name. The default is hnb659fds.

This is the key!!!

–qualifier is a string appended to all resource names in the bootstrap stack. Using a different qualifier allows you to provision multiple bootstrap stacks in the same environment and avoid resource name collisions. The default is hnb659fds (the value itself doesn’t matter). To change the qualifier, the CDK app must pass the changed value to the stack synthesizer. For details, see “Stack Synthesizer”.

Bootstrapping

Try running CDK’s --show-template option to check the template.

cdk bootstrap --show-template > bootstrap-template.yaml --profile dev --context stage=development

When I checked the template, I found this:

# bootstrap-template.yaml
FileAssetKeyArn:
  Description: The ARN of the KMS key used to encrypt the asset bucket (deprecated)
  Value:
    Fn::If:
      - CreateNewKey
      - Fn::Sub: ${FileAssetsBucketEncryptionKey.Arn}
      - Fn::Sub: ${FileAssetsBucketKmsKeyId}
  Export:
    Name:
      Fn::Sub: CdkBootstrap-${Qualifier}-FileAssetKeyArn

Even if I change the CDK stack name, if the Qualifier remains the default hnb659fds, the error will occur. Therefore, to resolve the error, it’s necessary to specify the Qualifier during Bootstrap. Like this:

cdk bootstrap --profile dev --context stage=development --qualifier rf4849gas

It’s a simple error, but with different stack names, it was an unexpected error. Be careful with the unhelpful error messages from CDK. By the way, this troublesome Qualifier error doesn’t end here. There will be more on that next time.