Extension framework - propagate error suggestions from event handlers and custom service targets (#7791)

Author: JeffreyCA

cli/azd/cmd/middleware/error.go

@@ -24,6 +24,7 @@ import (
 	"github.com/azure/azure-dev/cli/azd/internal/tracing/fields"
 	"github.com/azure/azure-dev/cli/azd/internal/tracing/resource"
 	"github.com/azure/azure-dev/cli/azd/pkg/alpha"
+	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
 	"github.com/azure/azure-dev/cli/azd/pkg/config"
 	"github.com/azure/azure-dev/cli/azd/pkg/environment"
 	"github.com/azure/azure-dev/cli/azd/pkg/environment/azdcontext"
@@ -175,6 +176,12 @@ func (e *ErrorMiddleware) Run(ctx context.Context, next NextFn) (*actions.Action
 		return actionResult, err
 	}
 
+	// Skip the YAML pipeline for typed extension errors so host-side rules don't
+	// override the extension's structured classification or user guidance.
+	if azdext.IsStructuredError(err) {
+		return actionResult, err
+	}
+
 	// Try to match error against known patterns and wrap with suggestion
 	if suggestion := e.errorPipeline.Process(ctx, err); suggestion != nil {
 		return actionResult, suggestion

cli/azd/cmd/middleware/error_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/azure/azure-dev/cli/azd/pkg/alpha"
 	"github.com/azure/azure-dev/cli/azd/pkg/auth"
 	"github.com/azure/azure-dev/cli/azd/pkg/azapi"
+	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
 	"github.com/azure/azure-dev/cli/azd/pkg/config"
 	"github.com/azure/azure-dev/cli/azd/pkg/environment"
 	"github.com/azure/azure-dev/cli/azd/pkg/errorhandler"
@@ -231,6 +232,108 @@ func Test_ErrorMiddleware_PatternMatchingSuggestion(t *testing.T) {
 	require.NotEmpty(t, suggestionErr.Links, "Expected reference links")
 }
 
+// Test_ErrorMiddleware_ExtensionErrorWithSuggestion_BypassesPipeline verifies that
+// when an extension-supplied error (LocalError or ServiceError) already carries a
+// Suggestion, the YAML error-suggestion pipeline is short-circuited so it doesn't
+// override the extension's specific guidance with a generic one. Regression test
+// for https://github.com/Azure/azure-dev/issues/7706.
+func Test_ErrorMiddleware_ExtensionErrorWithSuggestion_BypassesPipeline(t *testing.T) {
+	t.Parallel()
+
+	mockContext := mocks.NewMockContext(context.Background())
+	cfg := config.NewEmptyConfig()
+	featureManager := alpha.NewFeaturesManagerWithConfig(cfg)
+	global := &internal.GlobalCommandOptions{
+		NoPrompt: true, // skip agentic handling
+	}
+	userConfigManager := config.NewUserConfigManager(mockContext.ConfigManager)
+	errorPipeline := errorhandler.NewErrorHandlerPipeline(nil)
+	middleware := NewErrorMiddleware(
+		&Options{Name: "test"},
+		mockContext.Console,
+		nil,
+		global,
+		featureManager,
+		userConfigManager,
+		errorPipeline,
+	)
+
+	// "QuotaExceeded" matches a known pattern in error_suggestions.yaml that would
+	// otherwise wrap into an *ErrorWithSuggestion (proven by
+	// Test_ErrorMiddleware_PatternMatchingSuggestion). The middleware must skip
+	// that wrapping when the extension already supplied a suggestion of its own.
+	extErr := &azdext.LocalError{
+		Message:    "Deployment failed: QuotaExceeded for resource",
+		Code:       "quota_exceeded",
+		Category:   azdext.LocalErrorCategoryUser,
+		Suggestion: "Extension-provided guidance: request a quota increase via the portal.",
+	}
+	nextFn := func(ctx context.Context) (*actions.ActionResult, error) {
+		return nil, extErr
+	}
+
+	result, err := middleware.Run(*mockContext.Context, nextFn)
+
+	require.Error(t, err)
+	require.Nil(t, result)
+
+	// The original LocalError must be returned unchanged — not wrapped in
+	// *ErrorWithSuggestion by the YAML pipeline.
+	var wrapped *internal.ErrorWithSuggestion
+	require.False(
+		t,
+		errors.As(err, &wrapped),
+		"YAML pipeline should not wrap an extension error that already has a Suggestion",
+	)
+	returned, ok := errors.AsType[*azdext.LocalError](err)
+	require.True(t, ok, "expected the original *LocalError to be returned")
+	require.Same(t, extErr, returned)
+	require.Equal(t, extErr.Suggestion, azdext.ErrorSuggestion(err))
+}
+
+func Test_ErrorMiddleware_StructuredExtensionErrorWithoutSuggestion_BypassesPipeline(t *testing.T) {
+	t.Parallel()
+
+	mockContext := mocks.NewMockContext(context.Background())
+	cfg := config.NewEmptyConfig()
+	featureManager := alpha.NewFeaturesManagerWithConfig(cfg)
+	global := &internal.GlobalCommandOptions{
+		NoPrompt: true,
+	}
+	userConfigManager := config.NewUserConfigManager(mockContext.ConfigManager)
+	errorPipeline := errorhandler.NewErrorHandlerPipeline(nil)
+	middleware := NewErrorMiddleware(
+		&Options{Name: "test"},
+		mockContext.Console,
+		nil,
+		global,
+		featureManager,
+		userConfigManager,
+		errorPipeline,
+	)
+
+	extErr := &azdext.LocalError{
+		Message:  "Deployment failed: QuotaExceeded for resource",
+		Code:     "quota_exceeded",
+		Category: azdext.LocalErrorCategoryUser,
+	}
+	nextFn := func(ctx context.Context) (*actions.ActionResult, error) {
+		return nil, extErr
+	}
+
+	result, err := middleware.Run(*mockContext.Context, nextFn)
+
+	require.Error(t, err)
+	require.Nil(t, result)
+
+	var wrapped *internal.ErrorWithSuggestion
+	require.False(t, errors.As(err, &wrapped))
+	returned, ok := errors.AsType[*azdext.LocalError](err)
+	require.True(t, ok)
+	require.Same(t, extErr, returned)
+	require.Empty(t, azdext.ErrorSuggestion(err))
+}
+
 func Test_ErrorMiddleware_NoPatternMatch(t *testing.T) {
 	t.Parallel()
 	mockContext := mocks.NewMockContext(context.Background())

cli/azd/cmd/middleware/middleware_coverage2_test.go

@@ -617,6 +617,34 @@ func TestUxMiddleware_Run_AzdextServiceErrorWithSuggestion(t *testing.T) {
 	require.Nil(t, result)
 }
 
+func TestUxMiddleware_Run_AzdextLocalErrorWithLinks(t *testing.T) {
+	t.Parallel()
+	console := mockinput.NewMockConsole()
+	m := &UxMiddleware{
+		options:         &Options{},
+		console:         console,
+		featuresManager: alpha.NewFeaturesManagerWithConfig(config.NewEmptyConfig()),
+	}
+
+	localErr := &azdext.LocalError{
+		Message: "Extension config missing",
+		Code:    "missing_config",
+		Links: []errorhandler.ErrorLink{{
+			URL:   "https://aka.ms/azd-errors#missing-config",
+			Title: "Missing config help",
+		}},
+	}
+
+	result, err := m.Run(t.Context(), func(_ context.Context) (*actions.ActionResult, error) {
+		return nil, localErr
+	})
+
+	require.Error(t, err)
+	require.Nil(t, result)
+	require.Contains(t, fmt.Sprint(console.Output()), "https://aka.ms/azd-errors#missing-config")
+	require.NotContains(t, fmt.Sprint(console.Output()), "Suggestion:")
+}
+
 func TestUxMiddleware_Run_AzdextLocalErrorWithoutSuggestion(t *testing.T) {
 	t.Parallel()
 	console := mockinput.NewMockConsole()

cli/azd/cmd/middleware/ux.go

@@ -68,14 +68,15 @@ func (m *UxMiddleware) Run(ctx context.Context, next NextFn) (*actions.ActionRes
 
 		// Bridge extension errors (LocalError/ServiceError) with suggestions to rich UX.
 		// Covers both CLI extension commands and gRPC service target errors.
-		if suggestion := azdext.ErrorSuggestion(err); suggestion != "" {
+		if suggestion := azdext.ErrorSuggestion(err); suggestion != "" || len(azdext.ErrorLinks(err)) > 0 {
 			message := azdext.ErrorMessage(err)
 			if message == "" {
 				message = err.Error()
 			}
 			displayErr := &ux.ErrorWithSuggestion{
 				Message:    message,
 				Suggestion: suggestion,
+				Links:      azdext.ErrorLinks(err),
 			}
 			m.console.Message(ctx, "")
 			m.console.MessageUxItem(ctx, displayErr)

cli/azd/grpc/proto/errors.proto

@@ -25,21 +25,28 @@ message ServiceErrorDetail {
 
 // LocalErrorDetail contains structured error information for local/validation failures.
 // Used when ErrorOrigin is ERROR_ORIGIN_LOCAL.
-message LocalErrorDetail {
-  string code = 1;      // Extension-defined error code (e.g., "invalid_config")
-  string category = 2;  // Error category (e.g., "user", "validation", "dependency", "internal")
-}
-
-// ExtensionError is a unified error message that can represent errors from different sources.
-// It provides structured error information for telemetry and error handling.
-message ExtensionError {
-  reserved 1, 3;            // Reserved for future use; do not reuse.
-  string message = 2;       // Human-readable error message
-  ErrorOrigin origin = 4;   // Where the error originated from
-  string suggestion = 5;    // Optional user-facing suggestion for resolving the error
-
-  // Source-specific structured details. Only one should be set based on origin.
-  oneof source {
+message LocalErrorDetail {
+  string code = 1;      // Extension-defined error code (e.g., "invalid_config")
+  string category = 2;  // Error category (e.g., "user", "validation", "dependency", "internal")
+}
+
+// ErrorLink contains a reference link with a URL and optional title.
+message ErrorLink {
+  string url = 1;    // Link target
+  string title = 2;  // Display text (falls back to the URL when empty)
+}
+
+// ExtensionError is a unified error message that can represent errors from different sources.
+// It provides structured error information for telemetry and error handling.
+message ExtensionError {
+  reserved 1, 3;            // Reserved for future use; do not reuse.
+  string message = 2;       // Human-readable error message
+  ErrorOrigin origin = 4;   // Where the error originated from
+  string suggestion = 5;    // Optional user-facing suggestion for resolving the error
+  repeated ErrorLink links = 6;  // Optional reference links rendered alongside the suggestion
+
+  // Source-specific structured details. Only one should be set based on origin.
+  oneof source {
     ServiceErrorDetail service_error = 10;
     LocalErrorDetail local_error = 11;
     // ToolErrorDetail tool_error = 12;

cli/azd/grpc/proto/event.proto

@@ -7,6 +7,7 @@ package azdext;
 option go_package = "github.com/azure/azure-dev/cli/azd/pkg/azdext";
 
 import "models.proto";
+import "errors.proto";
 
 // EventService defines methods for event subscription, invocation, and status updates.
 // Clients can subscribe to events and receive notifications via a bidirectional stream.
@@ -68,7 +69,10 @@ message ProjectHandlerStatus {
   // Status such as "running", "completed", "failed", etc.
   string status = 2;
   // Optional message providing further details.
+  // For backward compatibility with older hosts, populate this even when error is set.
   string message = 3;
+  // Optional structured error details (set when status is "failed").
+  ExtensionError error = 4;
 }
 
 // Client sends status updates for service events
@@ -80,5 +84,8 @@ message ServiceHandlerStatus {
   // Status such as "running", "completed", "failed", etc.
   string status = 3;
   // Optional message providing further details.
+  // For backward compatibility with older hosts, populate this even when error is set.
   string message = 4;
+  // Optional structured error details (set when status is "failed").
+  ExtensionError error = 5;
 }

cli/azd/internal/grpcserver/event_service.go

@@ -179,6 +179,15 @@ func (s *eventService) createProjectEventHandler(
 			}
 
 			if statusMsg.ProjectHandlerStatus.Status == "failed" {
+				if extErr := azdext.UnwrapError(statusMsg.ProjectHandlerStatus.Error); extErr != nil {
+					log.Printf(
+						"extension %s project hook %s failed with structured error: %v",
+						extension.Id,
+						eventName,
+						extErr,
+					)
+					return extErr
+				}
 				return fmt.Errorf(
 					"extension %s project hook %s failed: %s",
 					extension.Id,
@@ -297,6 +306,16 @@ func (s *eventService) createServiceEventHandler(
 			}
 
 			if statusMsg.ServiceHandlerStatus.Status == "failed" {
+				if extErr := azdext.UnwrapError(statusMsg.ServiceHandlerStatus.Error); extErr != nil {
+					log.Printf(
+						"extension %s service hook %s.%s failed with structured error: %v",
+						extension.Id,
+						args.Service.Name,
+						eventName,
+						extErr,
+					)
+					return extErr
+				}
 				return fmt.Errorf(
 					"extension %s service hook %s.%s failed: %s",
 					extension.Id,