Cognito UserPool updates fail with 'Invalid AttributeDataType input' while synthesized Schema is present; error mapping suggests destructive pool recreation

[chchu]

Environment

• @aws-amplify/backend 1.24.0 / @aws-amplify/backend-cli 1.9.0 / @aws-amplify/backend-auth 1.9.4 / @aws-amplify/auth-construct 1.11.2
• aws-cdk-lib 2.263.0 / aws-cdk 2.1134.0
• Node.js 22.22.3 / pnpm 10.25.0 / macOS
• Region: ap-northeast-1
• UserPool originally created 2024-11 by ampx sandbox (Amplify Gen2, defineAuth({ loginWith: { email: true } }))

Description

defineAuth({ loginWith: { email: true } }) synthesizes the UserPool with:

"Schema": [{ "Mutable": true, "Name": "email", "Required": true }]

Creating the pool works fine. However, any subsequent update to a mutable UserPool property fails while this Schema property is present in the template — even when Schema itself is completely unchanged between the deployed template and the new template.

We hit this when changing only AdminCreateUserConfig.InviteMessageTemplate / VerificationMessageTemplate text (mutable properties).

Experiments (all reproduced 2026-08-03)

1. Schema unchanged (byte-identical to deployed template), only message-template text changed:

UPDATE_FAILED  AWS::Cognito::UserPool
Resource handler returned message: "Invalid AttributeDataType input, consider using the
provided AttributeDataType enum. (Service: CognitoIdentityProvider, Status Code: 400,
Request ID: dd8370ec-4f06-4cc8-ae2b-4852731315c3)" (HandlerErrorCode: InvalidRequest)

2. Schema fully specified to exactly match the live pool (verified identical via DescribeUserPool: AttributeDataType: String, DeveloperOnlyAttribute: false, Mutable: true, Required: true, StringAttributeConstraints: {MinLength: "0", MaxLength: "2048"}):

UPDATE_FAILED  AWS::Cognito::UserPool
Resource handler returned message: "Required custom attributes are not supported currently.
(Service: CognitoIdentityProvider, Status Code: 400,
Request ID: d4d0bdc0-4a35-4754-9d72-a19d88eda1f1)" (HandlerErrorCode: InvalidRequest)

3. Schema property removed from the template via cfnUserPool.addPropertyDeletionOverride("Schema"):

Update succeeds. DescribeUserPool confirms the live schema is unchanged (email still Required: true), all users intact.

The behavior suggests the CloudFormation AWS::Cognito::UserPool resource handler treats schema entries in the desired state as custom attribute additions during updates, even when they describe the existing standard email attribute and are unchanged from the previous template. The root cause is likely the CFN resource handler (service side) rather than this repo, but I'm filing here because (a) every Gen2 app synthesizes this exact Schema shape, so any Gen2 app that later touches a mutable UserPool property can hit this wall, and (b) the ampx error mapping makes the failure worse (below).

Error mapping concern

ampx maps this failure to:

[CFNUpdateNotSupportedError] User pool attributes cannot be changed after a user pool has been created.
Resolution: To change these attributes, remove `defineAuth` from your backend, deploy, then add it back.
Note that removing `defineAuth` and deploying will delete any users stored in your UserPool.

In this case no user-pool attribute change was intended or present in the diff — only mutable message templates changed. Following the suggested resolution would destroy all users unnecessarily. Please consider detecting the "Schema unchanged, other mutable properties changed" case and not steering users toward deleting their user pool.

Steps to reproduce

1. ampx sandbox with defineAuth({ loginWith: { email: true } }) → pool created successfully.
2. Change any mutable UserPool property, e.g. in backend.ts:

const { cfnUserPool } = backend.auth.resources.cfnResources;
cfnUserPool.adminCreateUserConfig = {
  allowAdminCreateUserOnly: true,
  inviteMessageTemplate: {
    emailSubject: "New subject",
    emailMessage: "New body {username} {####}",
  },
};

3. ampx sandbox again → UPDATE_FAILED with the error from Experiment 1.

Expected behavior

Mutable UserPool properties can be updated when the synthesized Schema is unchanged.

Current workaround

cfnUserPool.addPropertyDeletionOverride("Schema");

Safe for existing pools (Cognito has no API to remove attributes, so removing the property cannot alter the live schema — verified). Downside: pools newly created from the template no longer mark email as required (mitigated by email being the username attribute).

Asks

1. Confirm/escalate to the CloudFormation Cognito resource handler team.
2. Improve the CFNUpdateNotSupportedError mapping so users are not directed to delete their user pool when the template's Schema is unchanged.

[chchu]

Additional context after searching for prior reports:

Cross-reference: the same root phenomenon has been tracked in aws/aws-cdk#8585 — open since June 2020 (25 comments). Plain CDK L2 users (standardAttributes, no escape hatches) hit the identical Invalid AttributeDataType input failure when an existing pool's update includes the synthesized Schema. So this appears to be a long-standing CloudFormation handler behavior rather than a recent regression, which makes waiting for a service-side fix an unreliable strategy.

Given that, it may be worth noting which parts are actionable in this repo independently of the CFN handler fix:

1. Error mapping (Ask 2 in the description): the deployer can diff the previous vs. desired template Schema for the UserPool. If it is unchanged, the failure is provably not a user-initiated attribute change, and the current resolution text ("remove defineAuth … will delete any users") steers users toward unnecessary data loss. This is fixable purely in cdk_error_mapper today.

2. Avoiding the failure itself: since email is the username attribute for loginWith: { email: true }, the Required: true schema declaration is largely redundant. Not emitting Schema for this configuration would eliminate the failure mode entirely. Empirically (see experiments above), removing the Schema property from an existing stack deploys cleanly and leaves the live pool schema untouched, so the migration path for existing stacks appears safe. I recognize this is a product/backward-compat decision rather than a pure bug fix.

The only thing that genuinely requires the service-side fix is keeping Schema declared in the template and having updates succeed.