Ability to easily provide custom error messages/suggestions/docs for errors.#6700
Open
wbreza wants to merge 3 commits intoAzure:mainfrom
Open
Ability to easily provide custom error messages/suggestions/docs for errors.#6700wbreza wants to merge 3 commits intoAzure:mainfrom
wbreza wants to merge 3 commits intoAzure:mainfrom
Conversation
wbreza
requested review from
JeffreyCA,
hemarina,
rajeshkamal5050,
tg-msft,
vhvb1989 and
weikanglim
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a pattern-based error suggestion system that transforms cryptic Azure errors into user-friendly, actionable guidance. When users encounter well-known errors like quota limits or authentication failures, azd now displays a clear message, actionable suggestion, documentation link, and the raw error (de-emphasized in grey).
Changes:
- Adds YAML-based error pattern configuration in
resources/error_suggestions.yamlwith 279 lines covering quota, authentication, deployment, network, container, and tool-related errors - Implements pattern matching engine with regex support and caching in
pkg/errorhandler/ - Enhances
ErrorWithSuggestiontype with optionalMessageandDocUrlfields (backward compatible) - Integrates error suggestion service into error middleware to automatically wrap matching errors
- Updates UX middleware to display enhanced error format with user-friendly messaging
- Adds comprehensive test coverage and documentation
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| cli/azd/resources/error_suggestions.yaml | New YAML configuration defining 20+ error patterns with user-friendly messages and actionable suggestions |
| cli/azd/resources/resources.go | Embeds error_suggestions.yaml file into the binary |
| cli/azd/pkg/errorhandler/types.go | Defines types for error suggestion rules and matching results |
| cli/azd/pkg/errorhandler/matcher.go | Implements pattern matching engine with regex caching |
| cli/azd/pkg/errorhandler/service.go | Service that loads YAML config and matches errors against patterns |
| cli/azd/pkg/errorhandler/matcher_test.go | Comprehensive tests for pattern matching and service |
| cli/azd/pkg/output/ux/error_with_suggestion.go | UX component for displaying enhanced error format |
| cli/azd/pkg/output/ux/error_with_suggestion_test.go | Tests for error display formatting |
| cli/azd/internal/errors.go | Enhanced ErrorWithSuggestion type with Message and DocUrl fields |
| cli/azd/cmd/middleware/error.go | Integrates error suggestion service into error middleware |
| cli/azd/cmd/middleware/error_test.go | Tests for pattern matching integration and backward compatibility |
| cli/azd/cmd/middleware/ux.go | Updates UX middleware to use enhanced error display |
| cli/azd/cmd/container.go | Registers ErrorSuggestionService in DI container |
| cli/azd/docs/error-suggestions.md | Comprehensive documentation on using and extending the error suggestion system |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| result, err := middleware.Run(*mockContext.Context, nextFn) | ||
|
|
||
| // Should return error without AI intervention in no-prompt mode |
There was a problem hiding this comment.
Misleading comment: The comment states "Should return error without AI intervention in no-prompt mode" but this test is actually checking the scenario where the LLM alpha feature is disabled (NoPrompt is false in line 64). The comment should clarify that this tests the case where the LLM feature is disabled, not no-prompt mode.
Suggested change
| // Should return error without AI intervention in no-prompt mode | |
| // Should return error without AI intervention when the LLM alpha feature is disabled |
Collaborator
There was a problem hiding this comment.
I don't think this change copilot is suggesting is correct. I think it's conflating no-prompt mode for agent interaction with the alpha agentic mode. @wbreza pls confirm
Comment on lines
+14
to
+16
| type PatternMatcher struct { | ||
| // compiledPatterns caches compiled regex patterns for performance | ||
| compiledPatterns map[string]*regexp.Regexp |
There was a problem hiding this comment.
Potential concurrency issue: The compiledPatterns map is not thread-safe. If the PatternMatcher is shared across goroutines (which might happen since ErrorSuggestionService is registered as a singleton in the DI container), concurrent access to the map could lead to race conditions. Consider using sync.RWMutex to protect map access, or use sync.Map for concurrent access patterns.
vhvb1989
reviewed
Feb 3, 2026
| func TestErrorSuggestionService_FirstMatchWins(t *testing.T) { | ||
| service := NewErrorSuggestionService() | ||
|
|
||
| // An error that could match multiple patterns should return the first match |
Member
There was a problem hiding this comment.
How can we prevent that in the futrure, we don't create an entry for an error that overrule others and unintentionally changes all
Collaborator
There was a problem hiding this comment.
Do you mean a new error pattern?
Member
There was a problem hiding this comment.
Yes, a new pattern.
The current implementation resolves multiple patterns with a match by taking the first match.
This means that the order will decide the importance of each pattern. This could lead to a future scenario where it is hard to pick the right place for a new pattern if it could re-wire the existing pattern after it.
I guess we can cross that bridge when we get there 😜
JeffreyCA
reviewed
Feb 3, 2026
Contributor
There was a problem hiding this comment.
Could we consider making ErrorWithSuggestion usable from extensions as well? Currently it's in internal which makes it hard to reuse outside of core. I saw the azd x extension uses its own UserFriendlyError but would be great to have something shared
We're facing similar challenges in the AI Agents extension (see #6683)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Collaborator
|
I'm very excited about this change |
kristenwomack
approved these changes
Feb 4, 2026
Collaborator
Azure Dev CLI Install InstructionsInstall scriptsMacOS/Linux
bash: pwsh: WindowsPowerShell install MSI install Standalone Binary
MSI
Documentationlearn.microsoft.com documentationtitle: Azure Developer CLI reference
|
vhvb1989
approved these changes
Feb 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a pattern-based error suggestion system that transforms cryptic Azure errors into actionable guidance.
What it does
resources/error_suggestions.yamlExample output
Adding new patterns
Edit
resources/error_suggestions.yaml: