(core): refactor failed with (seemingly) identical resources

[sdasgupta-spectra]

Describe the bug

Firstly, I'd like to say thanks so much for implementing this feature! It's timely and should be super useful. I am attempting to perform a refactor, but stuck on one state machine that cdk refactor is unable to reconcile as unchanged between stacks. I had initially been having the same issues on another state machine, but realized that some of the unicode characters hadn't translated properly to the CloudFormation template and was able to get refactor working there.

This state machine has no diff between the local template and what's on CloudFormation except for the following log groups at the end (also being refactored), but I'm confused why this would have worked on the other state machine that had almost the same log group definitions.

       {
        "CloudWatchLogsLogGroup": {
         "LogGroupArn": {
-         "Fn::GetAtt": [
-          "betapipelinedefinitionloggroup<...>",
-          "Arn"
-         ]
+         "Fn::ImportValue": "cw-stack:ExportsOutputFnGetAttdalgostatemachineloggroup<...>"
         }
        }
       }
@@ -720,7 +717,7 @@
      "Level": "ERROR"
     },
     "RoleArn": {
-     "Fn::ImportValue": "shared-resources-stack:ExportsOutputFnGetAttalgostatemachinerole<...>"
+     "Fn::ImportValue": "iam-stack:ExportsOutputFnGetAttalgostatemachinerole<...>"
     },
     "StateMachineName": "beta-pipeline-definition",
     "StateMachineType": "STANDARD",
@@ -732,15 +729,6 @@
     ]
    },
    "Metadata": {
-    "aws:cdk:path": "beta-pipeline-stack/beta-pipeline-definition"
+    "aws:cdk:path": "statemachine-stack/beta-pipeline-definition"
    }
   },

Any assistance here would be appreciated or debugging steps that might elucidate why the stacks are showing as not the same.

The exact error I'm seeing is listed below.

Running a verbose output with this didn't seem to give more information about why the stacks don't match. I am including the statemachine-stack as an additional stack with --additional-stack-name=<STACK> and the other resources in that stack are not causing a problem.

Regression Issue

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

Last Known Working CDK Library Version

No response

Expected Behavior

Clean refactor with the cdk refactor recognizing that beta-pipeline-definition is the same between the old and new stack.

Current Behavior

Refactor failed: A refactor operation cannot add, remove or update resources. Only resource moves and renames are allowed.
The following resources are present only in the AWS environment:
  - statemachine-stack/beta-pipeline-definition

The following resources are present only in your CDK application:
  - beta-pipeline-stack/beta-pipeline-definition

Reproduction Steps

cdk refactor --unstable=refactor -c env=dev --dry-run --additional-stack-name=statemachine-stack <all-stacks-to-include>

Possible Solution

I tried comparing the CloudFormation template for the old resource with the new one that is generated in cdk.out using a git diff. Looking for a way to confirm difference/similarities between these two or understand better how the cdk refactor command determines whether or not there is a difference.

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.219.0

AWS CDK CLI version

2.1029.4 (build 09c0061)

Node.js Version

v22.17.0

OS

MacOS 15.6.1 (24G90)

Language

TypeScript

Language Version

^5.9.3

Other information

No response

[pahud]

Hi @sdasgupta-spectra

Thank you for your report. I was able to reproduce this issue. Let me log my reproduction steps below:

Steps Performed

1. Initial Deployment

lib/refactor-test-stack.ts:

import * as cdk from 'aws-cdk-lib';
import * as sfn from 'aws-cdk-lib/aws-stepfunctions';
import * as iam from 'aws-cdk-lib/aws-iam';
import { Construct } from 'constructs';

export class RoleStack extends cdk.Stack {
  public readonly role: iam.Role;

  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    this.role = new iam.Role(this, 'SfnRole', {
      assumedBy: new iam.ServicePrincipal('states.amazonaws.com'),
    });
  }
}

export class MachineStack extends cdk.Stack {
  constructor(scope: Construct, id: string, role: iam.Role, props?: cdk.StackProps) {
    super(scope, id, props);
    
    new sfn.StateMachine(this, 'TestMachine', {
      stateMachineName: 'refactor-test-machine',
      definitionBody: sfn.DefinitionBody.fromChainable(
        new sfn.Pass(this, 'Pass')
      ),
      role: role,
    });
  }
}

bin/refactor-test.ts:

#!/usr/bin/env node
import * as cdk from 'aws-cdk-lib';
import { RoleStack, MachineStack } from '../lib/refactor-test-stack';

const app = new cdk.App();

const roleStack = new RoleStack(app, 'RoleStack');
new MachineStack(app, 'MachineStack', roleStack.role);

Deployed Structure:

RoleStack (deployed)
  └── IAM Role

MachineStack (deployed)
  └── State Machine "refactor-test-machine"
      └── RoleArn: Fn::ImportValue "RoleStack:ExportsOutput..."

2. Refactored Configuration

lib/refactor-test-stack-v2.ts:

import * as cdk from 'aws-cdk-lib';
import * as sfn from 'aws-cdk-lib/aws-stepfunctions';
import * as iam from 'aws-cdk-lib/aws-iam';
import { Construct } from 'constructs';

export class NewRoleStack extends cdk.Stack {
  public readonly role: iam.Role;

  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    this.role = new iam.Role(this, 'SfnRole', {
      assumedBy: new iam.ServicePrincipal('states.amazonaws.com'),
    });
  }
}

export class NewMachineStack extends cdk.Stack {
  constructor(scope: Construct, id: string, role: iam.Role, props?: cdk.StackProps) {
    super(scope, id, props);
    
    new sfn.StateMachine(this, 'TestMachine', {
      stateMachineName: 'refactor-test-machine',
      definitionBody: sfn.DefinitionBody.fromChainable(
        new sfn.Pass(this, 'Pass')
      ),
      role: role,
    });
  }
}

bin/refactor-test-v2.ts:

#!/usr/bin/env node
import * as cdk from 'aws-cdk-lib';
import { NewRoleStack, NewMachineStack } from '../lib/refactor-test-stack-v2';

const app = new cdk.App();

const roleStack = new NewRoleStack(app, 'NewRoleStack');
new NewMachineStack(app, 'MachineStack', roleStack.role);

Refactored Structure:

NewRoleStack (new)
  └── IAM Role

MachineStack (refactored)
  └── State Machine "refactor-test-machine"
      └── RoleArn: Fn::ImportValue "NewRoleStack:ExportsOutput..."

3. Refactor Command Executed

npx cdk refactor --unstable=refactor --dry-run \
  --additional-stack-name=NewRoleStack MachineStack

Visual Representation

INITIAL DEPLOYMENT (WORKING)
=============================

┌─────────────────┐
│   RoleStack     │
│                 │
│  ┌──────────┐  │
│  │ IAM Role │──┼────┐
│  └──────────┘  │    │
└─────────────────┘    │
                       │ Fn::ImportValue
                       │ "RoleStack:ExportsOutput..."
                       │
┌──────────────────────▼──────────────┐
│        MachineStack                 │
│                                     │
│  ┌──────────────────────────────┐  │
│  │  State Machine               │  │
│  │  "refactor-test-machine"     │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘


REFACTORED CONFIGURATION (FAILS)
=================================

┌─────────────────┐
│  NewRoleStack   │
│                 │
│  ┌──────────┐  │
│  │ IAM Role │──┼────┐
│  └──────────┘  │    │
└─────────────────┘    │
                       │ Fn::ImportValue
                       │ "NewRoleStack:ExportsOutput..."
                       │
┌──────────────────────▼──────────────┐
│        MachineStack                 │
│                                     │
│  ┌──────────────────────────────┐  │
│  │  State Machine               │  │
│  │  "refactor-test-machine"     │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘


THE PROBLEM
===========

AWS CloudFormation sees:
┌─────────────────────────────────────┐
│ MachineStack/TestMachine            │
│ RoleArn: RoleStack:ExportsOutput... │
└─────────────────────────────────────┘

CDK synthesizes:
┌─────────────────────────────────────────┐
│ MachineStack/TestMachine                │
│ RoleArn: NewRoleStack:ExportsOutput...  │
└─────────────────────────────────────────┘

cdk refactor comparison:
    ╔════════════════════════════════════╗
    ║  ❌ IMPORT SOURCE MISMATCH!       ║
    ║                                    ║
    ║  RoleStack ≠ NewRoleStack          ║
    ║                                    ║
    ║  Treats as DIFFERENT resource!     ║
    ╚════════════════════════════════════╝

But it's THE SAME state machine!
    ✓ Same StateMachineName
    ✓ Same Definition
    ✓ Same Type
    ✗ Different import source → FAILS

ERROR REPRODUCED ✅

❌  Refactor failed: A refactor operation cannot add, remove or update resources.
Only resource moves and renames are allowed.

The following resources are present only in the AWS environment:
  - MachineStack/TestMachine/Resource

The following resources are present only in your CDK application:
  - MachineStack/TestMachine/Resource

Root Cause Identified

Deployed Template:

RoleArn:
  Fn::ImportValue: "RoleStack:ExportsOutputFnGetAttSfnRole127BDE63Arn41453CFF"

New CDK Template:

RoleArn:
  Fn::ImportValue: "NewRoleStack:ExportsOutputFnGetAttSfnRole127BDE63Arn41453CFF"

The Difference: Import source changed from RoleStack to NewRoleStack

Analysis

The cdk refactor command:

1. Compares the deployed CloudFormation template with the synthesized CDK template
2. Detects that RoleArn property has a different Fn::ImportValue source
3. Treats this as a resource modification rather than a resource move
4. Fails with the confusing error that the resource exists in both places but doesn't match

Conclusion

This confirms issue #35718. The cdk refactor command cannot handle:

• Cross-stack reference source changes (RoleStack → NewRoleStack)
• Import value name changes even when pointing to semantically equivalent resources
• Stack reorganization where dependencies are renamed

This seems to be a limitation that cdk refactor cannot handle changes to cross-stack reference sources (Fn::ImportValue values). I am bringing this up to the team for further review.