fix(backend-deployer): map toolkit-lib countAssemblyResults crash to a fault

[sharonyajain]

Problem

npx ampx sandbox and ampx pipeline-deploy crash during synth with a generic, misleading error that blames the customer's backend code:

[SyntaxError] Unable to build the Amplify backend definition.
 ∟ Caused by: [TypeError] Cannot convert undefined or null to object
Resolution: Check the Caused by error and fix any issues in your backend code

Running with --debug shows the crash is not in the customer's amplify/backend.ts at all — it originates inside @aws-cdk/toolkit-lib:

TypeError: Cannot convert undefined or null to object
    at Object.values (<anonymous>)
    at .../@aws-cdk/toolkit-lib/lib/toolkit/private/count-assembly-results.js
    at countAssemblyResults (.../count-assembly-results.js)
    at synthAndMeasure (.../toolkit.js)
    at async Toolkit.synth (.../toolkit.js)

countAssemblyResults calls Object.values(stack.metadata) with no null guard, and at least one nested stack that a Gen 2 backend (auth + multi-model data + storage) generates has metadata undefined — so Object.values(undefined) throws. This is a library bug, not a customer error, but backend-deployer re-wraps the TypeError via the generic TypeError → SyntaxError mapping and tells the customer to fix their own backend.

Issue number, if available: #3316

Changes

• cdk_error_mapper.ts: add a specific branch — placed before the generic TypeError branch — that detects this crash signature (TypeError + Cannot convert undefined or null to object + countAssemblyResults in the stack) and maps it to a fault (CDKSynthAssemblyMetadataFault) with an accurate, non-blaming message and a resolution that points at the upstream bug, instead of a customer-facing SyntaxError. The original error is preserved as the cause.

Note on scope: this PR only reclassifies the error so customers are no longer told to debug backend code that is not at fault. It does not fix the crash itself — the missing null guard lives in @aws-cdk/toolkit-lib and the actual fix belongs upstream in aws/aws-cdk-cli (Object.values(s.metadata ?? {}), tracked in aws/aws-cdk-cli#1952). A @aws-cdk/toolkit-lib version bump was considered but dropped: no published release contains the guard yet, so bumping would not fix the crash, and main deliberately pins 1.32.0.

Corresponding docs PR, if applicable: N/A

Validation

• Added 3 unit tests in cdk_error_mapper.test.ts:
  • the crash signature maps to CDKSynthAssemblyMetadataFault and is classified as a FAULT (not a customer ERROR);
  • the original TypeError is preserved as the cause;
  • an unrelated TypeError still maps to the existing backend SyntaxError (no regression / over-broad match).
• backend-deployer error-mapper suite: 65/65 pass. tsc --build on backend-deployer clean, prettier + eslint clean.
• Manual verification: N/A — the change is error classification only; unit coverage over getAmplifyError exercises the exact mapping path.

Checklist

• If this PR includes a functional change to the runtime behavior of the code, I have added or updated automated test coverage for this change.
• If this PR requires a change to the Project Architecture README, I have included that update in this PR.
• If this PR requires a docs update, I have linked to that docs PR above.
• If this PR modifies E2E tests, makes changes to resource provisioning, or makes SDK calls, I have run the PR checks with the run-e2e label set.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

no linked-issue close: partially addresses #3316 (improves the error message); the underlying crash fix is upstream in aws/aws-cdk-cli, so this PR intentionally does not close the issue.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3bc92bf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 24 packages

Name	Type
@aws-amplify/backend	Minor
@aws-amplify/backend-cli	Minor
create-amplify	Minor
@aws-amplify/backend-data	Minor
@aws-amplify/backend-deployer	Minor
@aws-amplify/backend-storage	Minor
@aws-amplify/hosting	Major
@aws-amplify/platform-core	Minor
@aws-amplify/ai-constructs	Minor
@aws-amplify/auth-construct	Minor
@aws-amplify/backend-ai	Minor
@aws-amplify/backend-auth	Minor
@aws-amplify/backend-function	Minor
@aws-amplify/backend-output-storage	Minor
@aws-amplify/cli-core	Patch
@aws-amplify/client-config	Patch
@aws-amplify/deployed-backend-client	Patch
@aws-amplify/form-generator	Patch
@aws-amplify/integration-tests	Patch
@aws-amplify/model-generator	Patch
@aws-amplify/plugin-types	Minor
@aws-amplify/sandbox	Patch
@aws-amplify/seed	Patch
@aws-amplify/backend-notifications	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[sharonyajain]

This PR is merged: aws/aws-cdk-cli#1952

[Simone319]

One non-blocking note that can't be line-anchored here because the CDKDeploymentError union is unchanged by this PR: CDKSynthAssemblyMetadataFault is passed as a bare string to AmplifyFault but isn't a member of the CDKDeploymentError union (~line 643), unlike every other named error. It compiles (the constructor accepts string), but callers that exhaustively switch on CDKDeploymentError won't see this fault and nothing keeps the literal and the union in sync — worth adding it to the union.

[sharonyajain]

@Simone319 on the CDKDeploymentError union note: fixed in 3bc92bfc — added CDKSynthAssemblyMetadataFault to the CDKDeploymentError union so the named fault is consistent with every other error there (previously it compiled only because AmplifyFault's first param accepts a bare string). Both of your notes are addressed in that commit.

[sharonyajain]

@Simone319 on the dead-code note (cdk_error_mapper.ts CDKSynthAssemblyMetadataFault branch): fixed in 3bc92bfc — added a TODO above the branch linking aws/aws-cdk-cli#1952 and noting that once a @aws-cdk/toolkit-lib release ships the guard and this package bumps its pin, countAssemblyResults stops throwing and this branch becomes dead code to remove as part of that bump. Left the branch in place for now since no fixed toolkit-lib release exists yet (main still pins 1.32.0). (Replying here rather than in-thread since the rebase orphaned the original inline anchor.)