❗ NOTICE (aws-cdk-lib): Python/Java/C#/Go - Reference interfaces moved to new submodules

[ourkwest]

Status: Resolved

What is the issue?

Reference interface (such as IBucketRef, IRoleRef, etc.) are a new feature introduced in v2.215.0. The original implementation was co-locating the interfaces within the service module. However this causes cyclic dependencies between service modules for many of the use cases this feature was intended for. We therefore consider the original interface locations a bug that we are now fixin.

In aws-cdk-lib v2.224.0, reference interfaces were moved to a new aws-cdk-lib.interfaces submodule to prevent these cyclic dependencies. While TypeScript users are unaffected due to type aliases left in the original locations, this change is breaking for Python, Java, C# and Golang users who reference these interfaces directly.

Error message

Java:

cannot find symbol: class ResourceEnvironment
cannot find symbol: class BucketReference

Python:

ImportError: cannot import name 'ResourceEnvironment' from 'aws_cdk'
ImportError: cannot import name 'BucketReference' from 'aws_cdk.aws_s3'

C#:

error CS0246: The type or namespace name 'ResourceEnvironment' could not be found
error CS0246: The type or namespace name 'BucketReference' could not be found

Go:

package awscdk/v2 is not in GOROOT
package awscdk/v2/awss3 is not in GOROOT
could not import github.com/aws/aws-cdk-go/awscdk/v2 (no required module provides package)

What is the impact?

Java and C# applications using aws-cdk-lib that reference these interfaces will fail to compile after upgrading to v2.224.0 or later. This affects any code that directly imports or uses these reference interface classes.

Required changes

Update all references in your code to use the new locations of these classes. See below for per language examples.

Who is affected?

Java and C# developers using aws-cdk-lib v2.224.0 or later who:

• Implement or reference L2 reference interfaces (e.g., IBucketRef, IRoleRef)
• Use classes like ResourceEnvironment or BucketReference

TypeScript users are NOT affected as type aliases remain in the original locations. We strongly recommend all TypeScript users update their code to the new import locations anyway. The original locations are deprecated.

How do I resolve this?

Update your import statements to reference the new interface locations:

Java:

// Old
import software.amazon.awscdk.ResourceEnvironment;
import software.amazon.awscdk.services.s3.BucketReference;

// New
import software.amazon.awscdk.interfaces.ResourceEnvironment;
import software.amazon.awscdk.interfaces.s3.BucketReference;

Python:

# Old
from aws_cdk import ResourceEnvironment
from aws_cdk.aws_s3 import BucketReference

# New
from aws_cdk.interfaces import ResourceEnvironment
from aws_cdk.interfaces.aws_s3 import BucketReference

C#:

// Old
using Amazon.CDK;
using Amazon.CDK.AWS.S3;

// New
using Amazon.CDK.Interfaces;
using Amazon.CDK.Interfaces.S3;

Go:

// Old
import (
   "github.com/aws/aws-cdk-go/awscdk/v2"
   "github.com/aws/aws-cdk-go/awscdk/v2/awss3"
)

// New
import (
   "github.com/aws/aws-cdk-go/awscdk/v2/interfaces"
   "github.com/aws/aws-cdk-go/awscdk/v2/interfaces/awss3"
)

Related issues

• fix: move reference interfaces to their own submodules #35971 - PR that introduced this change
• https://github.com/aws/aws-cdk/releases/tag/v2.224.0

---

Original User Report

Author: @ourkwest

Upgrading to aws-cdk-lib 2.224.0 of the Java library has caused some breaking changes.

The ResourceEnvironment and BucketReference classes have moved. Depending on use-cases, this can cause breakages in client code.

I'm raising this mostly so that anyone else having this problem will more easily find the solution.

The fix in my case was simply to update all references in my code to use the new locations of these classes.

software.amazon.awscdk.ResourceEnvironment
has moved to
software.amazon.awscdk.interfaces.ResourceEnvironment

software.amazon.awscdk.services.s3.BucketReference
has moved to
software.amazon.awscdk.interfaces.s3.BucketReference

These are briefly alluded to in the changelog as "move reference interfaces to their own submodules", but it's not clear from the release notes (https://github.com/aws/aws-cdk/releases/tag/v2.224.0) that this is a breaking change for some users.

Links: https://github.com/aws/aws-cdk/releases/tag/v2.224.0

[mrgrain]

Thanks @ourkwest Very good point!