chore: add error mappings and resolutions for circular dependency failures (#2342)

Author: Amplifiyer

.changeset/early-dodos-pull.md

@@ -0,0 +1,5 @@
+---
+'@aws-amplify/backend-deployer': patch
+---
+
+add mapping for circular dependency failures with resolution

packages/backend-deployer/src/cdk_error_mapper.test.ts

@@ -665,6 +665,20 @@ npm error enoent`,
     errorName: 'InvalidOrCannotAssumeRoleError',
     expectedDownstreamErrorMessage: undefined,
   },
+  {
+    errorMessage: `some-stack failed: ValidationError: Circular dependency between resources: [storage1, data1, function1] `,
+    expectedTopLevelErrorMessage:
+      'The CloudFormation deployment failed due to circular dependency found between nested stacks [storage1, data1, function1]',
+    errorName: 'CloudformationStackCircularDependencyError',
+    expectedDownstreamErrorMessage: undefined,
+  },
+  {
+    errorMessage: `The stack named named-stack failed to deploy: UPDATE_ROLLBACK_COMPLETE: Circular dependency between resources: [resource1, resource2] `,
+    expectedTopLevelErrorMessage:
+      'The CloudFormation deployment failed due to circular dependency found between resources [resource1, resource2] in a single stack',
+    errorName: 'CloudformationResourceCircularDependencyError',
+    expectedDownstreamErrorMessage: undefined,
+  },
 ];
 
 void describe('invokeCDKCommand', { concurrency: 1 }, () => {

packages/backend-deployer/src/cdk_error_mapper.ts

@@ -486,6 +486,32 @@ export class CdkErrorMapper {
       errorName: 'BackendSynthError',
       classification: 'ERROR',
     },
+    {
+      // This error pattern is observed when circular dependency is between stacks but not resources in a stack
+      errorRegex:
+        /ValidationError: Circular dependency between resources: \[(?<resources>.*)\]/,
+      humanReadableErrorMessage:
+        'The CloudFormation deployment failed due to circular dependency found between nested stacks [{resources}]',
+      resolutionMessage: `If you are using functions then you can assign them to existing nested stacks that are dependent on functions or functions depend on them, for example:
+1. If your function is defined as auth triggers, you should assign this function to auth stack.
+2. If your function is used as data resolver or calls data API, you should assign this function to data stack.
+To assign a function to a different stack, use the property 'resourceGroupName' in the defineFunction call and choose auth, data or any custom stack.
+
+If your circular dependency issue is not resolved with this workaround, please create an issue here https://github.com/aws-amplify/amplify-backend/issues/new/choose
+`,
+      errorName: 'CloudformationStackCircularDependencyError',
+      classification: 'ERROR',
+    },
+    {
+      // This error pattern is observed when circular dependency is between resources in a single stack, i.e. ValidationError is absent from the error message
+      errorRegex:
+        /(?<!ValidationError: )Circular dependency between resources: \[(?<resources>.*)\]/,
+      humanReadableErrorMessage:
+        'The CloudFormation deployment failed due to circular dependency found between resources [{resources}] in a single stack',
+      resolutionMessage: `If you are creating custom stacks or adding new CDK resources to amplify stacks, ensure that there are no cyclic dependencies. For more details see: https://aws.amazon.com/blogs/infrastructure-and-automation/handling-circular-dependency-errors-in-aws-cloudformation/`,
+      errorName: 'CloudformationResourceCircularDependencyError',
+      classification: 'ERROR',
+    },
     {
       errorRegex:
         /(?<stackName>amplify-[a-z0-9-]+)(.*) failed: ValidationError: Stack:(.*) is in (?<state>.*) state and can not be updated/,
@@ -523,6 +549,8 @@ export type CDKDeploymentError =
   | 'CDKResolveAWSAccountError'
   | 'CDKVersionMismatchError'
   | 'CFNUpdateNotSupportedError'
+  | 'CloudformationResourceCircularDependencyError'
+  | 'CloudformationStackCircularDependencyError'
   | 'CloudFormationDeletionError'
   | 'CloudFormationDeploymentError'
   | 'CommonNPMError'