Surface ARM error.message text for opaque InvalidTemplateDeployment failures

[spboyer]

Problem

1,017 InvalidTemplateDeployment errors per month (21.6% of all ITD errors) have no deeper error code in the chain — InvalidTemplateDeployment is the terminal frame. Users see a generic template validation error with no detail about what failed.

However, the ARM API response body contains an error.message field with human-readable text explaining the specific validation failure. This message is not currently surfaced in azd's error output.

Telemetry Data (March 2026, 23 days)

Metric	Value
Opaque ITD errors (no deeper code)	1,017
Unique machines affected	366
Avg wait before failure	122s
User-hours wasted/month	~35h

Service Breakdown of Opaque Errors

Service Target	Count	Share
(unknown)	231	23%
containerapp	200	20%
function	146	14%
containerapp-dotnet (multi)	79+	8%
azure.ai.agent	61	6%
appservice	42	4%

User Impact

• 65% of these users retry and fail again — the current error output gives them no information to guide a fix
• Container Apps (all variants) accounts for 47% of opaque errors

Proposed Solution

In the ARM deployment error handling code (likely deployments.go or bicep_provider.go), when parsing ARM error responses:

1. Capture error.message (and nested error.details[].message) in addition to error.code
2. Surface the message text in the error suggestion output or the deployment error display
3. For the telemetry error.service.errorcode field, consider adding a frame for the message content or a hash of it, so future analysis can classify these errors

Relationship to Other PRs

• Route error spans through MapError to reduce UnknownFailure bucket #7241 (MapError routing) — improves error code classification but does not extract error messages. Complementary.
• Add Container Apps and ARM error suggestions #7250 (Container Apps error suggestions) — adds pattern-matched suggestions. Message extraction would make these suggestions more specific.
• Improve Container Apps provisioning error handling and classification #7249 (Container Apps error handling issue) — this is a broader version of the same problem.

Example

Today:

ERROR: deployment failed: error deploying infrastructure: InvalidTemplateDeployment

After this fix:

ERROR: deployment failed: InvalidTemplateDeployment
  → The resource 'myapp-containerapp' property 'configuration.ingress.targetPort' value '0' is invalid.
    Must be between 1 and 65535.

[weikanglim]

The message is showing up for me today (I could see improvements we would make to the formatting):

deployment failed: error deploying infrastructure: validating deployment to subscription:

Validation Error Details:
InvalidTemplateDeployment: The template deployment 'weilim-capp-1774375200' is not valid according to the validation procedure. The tracking id is '6bf866f8-61f3-48cf-93da-eb5ac90ef80d'. See inner errors for details.
ValidationForResourceFailed: Validation failed for a resource. Check 'Error.Details[0]' for more information.
ContainerAppInvalidIngressTargetPort: The Ingress's TargetPort must be in the range of [0,65535] or null. If targetPort is 0 or null the system will try to auto-detect the port for the app.

The message should be automatically surfaced by cli/azd/pkg/azapi/azure_deployment_error.go. I'm wondering if this isn't happening in some cases, or if it's likely that the LLM's analysis has skipped this detail?

consider adding a frame for the message content or a hash of it, so future analysis can classify these errors

This can be highly tricky given it's a tree of errors -- but we can certainly get the message from ARM's dataset today.

[rajeshkamal5050]

Done. ARM error messages are now surfaced for InvalidTemplateDeployment failures — users see the specific validation detail instead of a generic error.

If you're still seeing opaque errors on a recent version, please reopen with the error output.