ConstructsFeatureFlagsReport fails with CDK Pipelines: App.of() returns Stage instead of App

[agogna]

Description

In version 2.96.0, the ConstructsFeatureFlagsReport.ensure() method uses App.of(scope) to find the root App. However, when Solutions Constructs are used within CDK Pipelines (specifically when constructs are instantiated in a Stage within a Pipeline), App.of() returns the Stage object instead of the root App, causing a validation error.

Code Reference

The issue originates from this line in constructs-feature-flags.ts:

aws-solutions-constructs/source/patterns/@aws-solutions-constructs/core/lib/constructs-feature-flags.ts

Line 31 in f24ff08

const app = App.of(scope);

public static ensure(scope: Construct) {
  const app = App.of(scope);  // Returns Stage in CDK Pipelines context
  if (!app) {
    throw new Error('Invalid scope provided to ConstructsFeatureFlagsReport');
  }
  const id = 'AwsSolutionsFeatureFlagsReport';
  if (!app.node.tryFindChild(id)) {
    new ConstructsFeatureFlagsReport(app, id);
  }
}

Error Message

ValidationError: ConstructsFeatureFlagsReport at 'HubPipeline/HubTest-EuWest1/AwsSolutionsFeatureFlagsReport' 
should be created in the scope of a Stack, but no Stack found
    at path [HubPipeline/HubTest-EuWest1] in aws-cdk-lib.Stage

Architecture

App (root)
└── CdkPipeline (Stack)
    └── TestStage-EuWest1 (Stage)  ← App.of() returns this Stage
        └── AppStack (Stack)
            └── AppConstruct (Construct)
                └── SnsToSqs (Solutions Construct)

When SnsToSqs calls ConstructsFeatureFlagsReport.ensure(this), the App.of(scope) traverses up the tree and stops at the first App instance it finds. However, in CDK Pipelines, the Stage class extends App (via composition), so App.of() returns the Stage instead of the root App.

Reproduction Steps

1. Create a CDK Pipeline with a Stage
2. Within the Stage, create a Stack
3. Within the Stack, use any Solutions Construct that instantiates SnsToSqs inside a Construct (not directly in a Stack)
4. Run cdk synth or cdk list

Expected Behavior

ConstructsFeatureFlagsReport should be created at the root App level, regardless of whether the construct is used within a CDK Pipeline Stage.

Actual Behavior

ConstructsFeatureFlagsReport is created at the Stage level, which causes a validation error because it's not in a Stack scope.

Environment

• AWS CDK: 2.231.0
• AWS Solutions Constructs: 2.96.0
• Node.js: 22.13.1
• TypeScript: 5.7.3

Workaround

Downgrade to AWS Solutions Constructs v2.92.0 or earlier, which doesn't include the ConstructsFeatureFlagsReport feature.

Additional Context

This issue was introduced in v2.93.0 when feature flag infrastructure was added (#1407). The feature appears to have been tested only with simple App → Stack hierarchies, not with CDK Pipelines that use Stages.

CDK Pipelines are a common pattern for multi-environment deployments, so this issue affects many production use cases.

[biffgaut]

Thanks - we'll check it out.

This is a really well done issue writeup!

[agogna]

Thanks to CoPilot 😄
I manually fixed the description because it contained some incorrect information.
(forgot to ask CoPilot to review the issue before opening it)

[biffgaut]

The original post had a proposed solution with a couple options, why did you edit/delete it?

[biffgaut]

I'm having trouble duplicating the behavior. I've created a pipeline and added a stage that launches the stack below:

import * as cdk from 'aws-cdk-lib';
import { Construct, Node } from 'constructs';
import { SnsToSqs, SnsToSqsProps } from '@aws-solutions-constructs/aws-sns-sqs';
import * as defaults from '@aws-solutions-constructs/core';
import { SNS_SUBSCRIPTIONS_SQS_DECRYPTION_POLICY } from 'aws-cdk-lib/cx-api';

export class StackAppStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new ConstructWrapper(this, 'wrapper', {});
  }
}


export class ConstructWrapper extends Construct {
  constructor(scope: Construct, id: string, props: SnsToSqsProps) {
    super(scope, id);

    console.log("************************ Calling ensure");
    const app = cdk.App.of(this);
    console.log(`App artifactId = ${app?.artifactId}`);
    const a = defaults.ConstructsFeatureFlagsReport.ensure(this);
    console.log(`Flag Value = ${cdk.FeatureFlags.of(scope).isEnabled(SNS_SUBSCRIPTIONS_SQS_DECRYPTION_POLICY)}`);
    const topApp: cdk.App = Node.of(scope).root as cdk.App;
    console.log(`topApp artifactId = ${topApp?.artifactId}`);
    // Create the problematic construct
    new SnsToSqs(this, 'some-construct', {});

  }
}

This launches SnsToSqs nested in another construct - that's how I interpreted the reproduction instructions. I also added calls to directly interact with the Feature Flag code in our core module. It prints out:

************************ Calling ensure
App artifactId = assembly-ThisIsTheId-test
Flag Value = true
topApp artifactId =

The flag is successfully accessed based on the App.of() value. The pipeline also launches this stack successfully. Any thoughts on why I'm seeing different behavior?