gen2-migration retain fails on large AppSync API stacks: CloudFormation 51,200-byte inline templateBody limit (blocks decommission)

[francescoRobin]

Description

amplify gen2-migration retain fails on any project whose generated AppSync API root CloudFormation template exceeds 51,200 bytes, because the command submits the modified template inline (templateBody) to CloudFormation, which enforces a 51,200-byte limit on inline templates. This blocks the decommission step of the official Gen1→Gen2 migration path (retain is the documented prerequisite before deleting the Gen1 root stack).

🛑 Failed: ValidationError: 1 validation error detected: Value '{...big template...}' at 'templateBody'
   failed to satisfy constraint: Member must have length less than or equal to 51200
🛑 Rollback is not supported for the retain step

The API root template is large because it inlines the auth-mode AuthRolePolicy* AWS::IAM::ManagedPolicy resources (one appsync:GraphQL statement per field, across all models). A schema with ~20+ @model types plus AWS_IAM auth easily pushes the root template past 51,200 bytes.

Related: #14790 (the issue that introduced the retain command).

Impact

• retain applies DeletionPolicy: Retain only to the stacks it processes before reaching the oversized API stack, then aborts. In our case it never reached the per-model nested stacks that own the DynamoDB tables.
• Because retain "has no rollback" and the update was rejected at validation, no changes are applied (stacks stay UPDATE_COMPLETE), but the migration cannot proceed to a clean Gen1 root-stack deletion — the documented decommission step is blocked.
• Reproducible and deterministic; affects any sufficiently large API.

Reproduction

1. Complete a Gen1→Gen2 migration (assess → lock → generate → deploy → refactor) for an app with a large AppSync API (many @model types + AWS_IAM additional auth, so the API root template > 51,200 bytes).
2. Run amplify gen2-migration retain from the Gen1 workspace.
3. Observe the ValidationError on templateBody for the api<name> root stack.

Root cause

retain calls CloudFormation UpdateStack with an inline TemplateBody. CloudFormation limits inline templates to 51,200 bytes; larger templates must be uploaded to S3 and referenced via TemplateURL (1 MB limit). The Amplify CLI already uses the S3/TemplateURL path for large templates during normal deploys, so the fix is to apply the same approach in the retain (and likely lock/refactor) stack-update code paths.

Suggested fix

When the modified template exceeds the inline limit, upload it to the deployment bucket and pass TemplateURL instead of TemplateBody.

Environment

• @aws-amplify/cli 14.5.0 (gen2-migration retain)
• region eu-central-1
• Gen1 app migrated to Gen2; ~23 @model types, multi-auth (Cognito user pools + AWS_IAM + API key).

Workaround

Skip the stock retain and either (a) rely on table-level DeletionProtectionEnabled + delete-stack --retain-resources <TableLogicalId> per nested stack, or (b) manually add DeletionPolicy: Retain to the stateful resources via S3-based update-stack, then delete the root.

[francescoRobin]

Follow-up: the manual workaround is also blocked — decommission is effectively unachievable for large nested apps without a tool fix

After hitting the retain failure above, I tried the obvious manual workaround — apply DeletionPolicy: Retain directly to the stateful resources (the per-model DynamoDB table child stacks) so the Gen1 root can be deleted cleanly. Two more walls, both reinforcing that this needs to be fixed in the tool, not worked around:

1. The model child-stack templates also exceed the 51,200-byte inline limit. It's not just the API root stack — aws cloudformation update-stack --template-body file://... is rejected for most api<name>-<Model>-<suffix> child stacks too. So any fix must use the S3 TemplateURL path everywhere retain updates a stack, not just for the root.

2. Nested stacks can't be updated standalone. For the few child templates small enough to attempt inline, update-stack fails with:

   ValidationError: Parameters: [referencetotransformerrootstack...Ref, ...GraphQLAPI...ApiId,
   ...ProfileNestedStack...Outputs..., authRoleName, unauthRoleName, env, ...] must have values
   

   These child stacks receive ~15 parameters from their parent (cross-stack GetAtt outputs, API id, deployment bucket, role names). A user can't reasonably reconstruct those by hand, so there is no clean manual path to apply Retain to the stateful resources — it has to be done by the tool walking the tree with the parent-supplied parameters intact.

Net impact: for a real-world Gen1 app (deeply nested AppSync API with ~20+ @model types + AWS_IAM auth), the documented decommission step (retain → delete Gen1 root) is currently not achievable, and there's no viable manual workaround. The only safe fallback is to leave the Gen1 stacks in place (dormant/locked) and rely on table-level DeletionProtectionEnabled to protect data — i.e. you can complete the migration and run Gen2 in production, but you cannot tear down the old Gen1 stacks.

Happy to provide a sanitized template/parameter dump if useful for repro.

[francescoRobin]

The workaround for this NOT TESTED in production yet, is to directly remove the cloudFormation stack after the postRefactor step. The resource are already retained by the lock command at the beginning of the migration so they are not deleted.
I am not sure this is the right solution but if it is I would change the documentation here to reflect it https://docs.amplify.aws/react/start/migrate-to-gen2/migrate-existing-app/

[kevinxu3]

+1 any updates on this