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.
• cdk_error_mapper.ts: add CDKSynthAssemblyMetadataFault to the CDKDeploymentError union so the named fault is consistent with every other error there (review nit).
• cdk_error_mapper.ts: add a TODO above the fault branch linking fix(toolkit-lib): guard against a stack with no metadata in countAssemblyResults aws/aws-cdk-cli#1952 — once a @aws-cdk/toolkit-lib release ships the merged null guard and this package bumps its pin, countAssemblyResults no longer throws and this branch becomes dead code to remove (review nit).

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 ?? {}), merged 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.

Supersedes #3329, which became un-reopenable after its head branch lost common history with main during a rebase. This PR is the same branch (fix/toolkit-lib-metadata-null-guard-3316) rebuilt cleanly on current main, carrying the original fix plus the two review nits above.

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: 617203c

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

This PR includes changesets to release 1 package

Name	Type
@aws-amplify/backend-deployer	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]

@Simone319 this PR supersedes #3329 (which became un-reopenable after its branch lost common history with main). Both of your review notes from #3329 are addressed here in 617203c3:

• Dead-code TODO (cdk_error_mapper.ts CDKSynthAssemblyMetadataFault branch): added a TODO above the branch linking fix(toolkit-lib): guard against a stack with no metadata in countAssemblyResults 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 in place for now since no fixed toolkit-lib release exists yet (main still pins 1.32.0).
• CDKDeploymentError union membership: 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).