AWS CDK S3 Construct Library (v1)

Common errors

• ImportError: cannot import name 'core' from 'aws_cdk'

  cause You are attempting to import `core` directly from `aws_cdk`, which is a common mistake when mixing CDK v1 and v2 import patterns, or if your virtual environment is not correctly set up for v1.
  fix For CDK v1, `core` should be imported as `import aws_cdk.core as cdk`. Ensure your `requirements.txt` specifies `aws-cdk.core` for v1. If you intended to use CDK v2, you should import `Stack` and other core modules directly from `aws_cdk_lib` (e.g., `from aws_cdk_lib import Stack, App`).

• The bucket that you tried to delete is not empty

  cause This occurs during `cdk destroy` if an S3 bucket is set with `removal_policy=cdk.RemovalPolicy.DESTROY` but still contains objects. AWS S3 prevents deletion of non-empty buckets.
  fix To allow CDK to delete the bucket and its contents, you must set both `removal_policy=cdk.RemovalPolicy.DESTROY` and `auto_delete_objects=True` when defining the `s3.Bucket` construct. Alternatively, manually empty the bucket before destroying the stack.

• An error occurred (BucketAlreadyOwnedByYou) when calling the CreateBucket operation: Your bucket name is not unique and you already own a bucket with that name.

  cause S3 bucket names must be globally unique across all AWS accounts, or at least unique within your account if `BucketAlreadyOwnedByYou` is seen. This error indicates you are trying to create a bucket with a name that already exists and is owned by your account (possibly from a previous failed deployment with `RETAIN` policy).
  fix Choose a different, globally unique bucket name (e.g., by appending `cdk.Aws.ACCOUNT_ID` or a random suffix). If the bucket exists and is orphaned from a previous CDK deployment, manually delete it or import it into your current stack.

• API: s3:PutBucketPolicy Access Denied

  cause The IAM user or role deploying the CDK stack lacks the necessary `s3:PutBucketPolicy` permissions on the target S3 bucket, or there's a conflict with `BlockPublicAccess` settings.
  fix Grant the deploying IAM entity `s3:PutBucketPolicy` permissions. Review the bucket's `block_public_access` settings; if `BlockPublicAccess.BLOCK_ALL` is set, it might prevent certain policy modifications. Ensure no conflicting explicit deny statements exist in other policies.

Warnings

• breaking AWS CDK v1 is End-of-Support (EOS) as of June 1, 2023. This `aws-cdk.aws-s3` package is no longer maintained. Continued use may expose your applications to security vulnerabilities or compatibility issues with newer AWS features.
  Fix: Migrate your CDK application to AWS CDK v2. This involves changing package dependencies from individual `aws-cdk.aws-s3` and `aws-cdk.core` to a consolidated `aws-cdk-lib` package and updating import statements. Consult the official AWS CDK v2 migration guide for detailed steps.
• gotcha By default, S3 buckets created with CDK (and CloudFormation) have a `removal_policy` of `RETAIN`. If you delete the CDK stack, the S3 bucket will NOT be deleted and will remain in your account, leading to potential resource leaks or conflicts if you try to recreate a bucket with the same name. Additionally, a non-empty bucket cannot be deleted by CloudFormation if `removal_policy` is `DESTROY` without `auto_delete_objects` enabled.
  Fix: To ensure an S3 bucket is deleted with its stack (and its contents), set both `removal_policy=cdk.RemovalPolicy.DESTROY` AND `auto_delete_objects=True` when defining the `s3.Bucket` construct. Use this with extreme caution in production environments as it leads to irreversible data loss.
• gotcha You might encounter 'Access Denied' errors when applying bucket policies, especially if the bucket already exists or if `BlockPublicAccess` is enabled. CloudFormation does not allow replacing or modifying bucket policies that were created outside its control.
  Fix: Ensure the IAM user/role deploying the stack has sufficient `PutBucketPolicy` permissions. If using an existing bucket, consider importing it into CDK or recreating it entirely within CDK control. If `block_public_access` is set (e.g., `s3.BlockPublicAccess.BLOCK_ALL`), this can interfere with custom bucket policies; temporarily disabling it, deploying, and re-enabling might be a workaround if truly necessary.
• gotcha Intermittent `CREATE_FAILED` errors for S3 Bucket Policies with 'Unable to retrieve Arn attribute for AWS::S3::Bucket, with error message Bucket not found'. This is a known CloudFormation dependency issue where the policy tries to access the bucket's ARN before it's fully provisioned.
  Fix: This issue is often intermittent. Retrying the `cdk deploy` command typically resolves it. In some cases, deploying the bucket without a policy first, then adding the policy in a subsequent deployment, can work.

Install

• pip install aws-cdk.aws-s3==1.204.0 Install specific v1 version
• npm install -g aws-cdk Install AWS CDK Toolkit (CLI) - required for deployment

Imports

• Bucket
  wrong:

  from aws_cdk_lib.aws_s3 import Bucket

  correct:

  from aws_cdk import aws_s3 as s3
  from aws_cdk import core

  Incorrect for CDK v1. This is the v2 import path. For v1, import `aws_s3` as a module and access `s3.Bucket`.
• Stack
  wrong:

  from aws_cdk_lib import Stack

  correct:

  from aws_cdk import core

  Incorrect for CDK v1. This is the v2 import path. For v1, `Stack` is available under the `core` module, typically imported as `cdk.Stack`.

Quickstart

This quickstart demonstrates how to define a basic S3 bucket using `aws-cdk.aws-s3` in a Python CDK application. It sets up a minimal stack and creates an S3 bucket with a globally unique name using the AWS account ID. Remember that `cdk.App().synth()` is used to generate the CloudFormation template. To deploy, you would run `cdk deploy` after bootstrapping your AWS environment.

import os
from aws_cdk import (  # type: ignore
    core as cdk,
    aws_s3 as s3
)

class MyS3Stack(cdk.Stack):
    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Define an S3 bucket
        # For production, consider adding specific bucket_name, versioned, encryption, and public access settings
        # A removal_policy of RETAIN is the default for stateful resources like S3 buckets.
        # If you want the bucket and its contents to be deleted with the stack, use RemovalPolicy.DESTROY and auto_delete_objects=True (see warnings).
        s3.Bucket(self, "MyFirstS3Bucket",
            versioned=False,
            bucket_name=f"my-unique-bucket-{cdk.Aws.ACCOUNT_ID}", # Bucket names must be globally unique
            removal_policy=cdk.RemovalPolicy.RETAIN, # Default for stateful resources
            # auto_delete_objects=True # Use with caution and ONLY if removal_policy is DESTROY
        )

app = cdk.App()
MyS3Stack(app, "MyS3Stack")
app.synth()