Problem

Telemetry analysis over 90 days (Nov 2025 - Feb 2026) shows that 28.22% of all azd errors (~36,132 of 128,054) are classified as UnknownError or internal.errors_errorString. This is the single largest error category and provides no actionable signal for diagnosing template or infrastructure failures.

Root Cause

The error classification logic in internal/cmd/errors.go (lines 166-171) uses a fallback that converts any untyped error into internal.<errorType>. Plain errors.New() strings become internal.errors_errorString. Additionally, the AppInsights exporter in internal/telemetry/appinsights-exporter/span_to_envelope.go (lines 64-70) assigns UnknownFailure when the span error description is empty.

Common error types that fall through unclassified include:

• context.DeadlineExceeded (network timeouts)
• TLS handshake failures
• Wrapped HTTP errors that are not *azcore.ResponseError
• DNS resolution failures

Proposed Solution

1. Add explicit classifiers in MapError() for common error patterns:
   • context.DeadlineExceeded and context.Canceled as internal.timeout and user.canceled
   • Network/TLS errors as internal.network.<type>
   • Wrapped HTTP status codes extracted from non-azcore errors
2. Sub-classify ARM deployment errors using the deepest error code from the error tree (e.g., service.arm.deployment.InsufficientQuota.failed instead of generic service.arm.deployment.failed)
3. Add debug-level logging of unclassified error types to enable ongoing triage
4. Consider enriching the AppInsights exporter to include the Go error type even when description is empty

Data Reference

Source: AzdProvisionErrorsByTemplate + AzdDeploymentErrorsByTemplate (DevCli on ddazureclients)

• UnknownError: 18,368 (14.34%)
• internal.errors_errorString: 10,737 (8.38%)
• Other internal.* codes: ~7,027 (5.49%)