Skip to content

refactor(compiler-cli): improve diagnostic with help link#64361

Merged
thePunderWoman merged 1 commit intoangular:mainfrom
splincode:feat/improved-error-message
Feb 20, 2026
Merged

refactor(compiler-cli): improve diagnostic with help link#64361
thePunderWoman merged 1 commit intoangular:mainfrom
splincode:feat/improved-error-message

Conversation

@splincode
Copy link
Contributor

@splincode splincode commented Oct 11, 2025 •
edited
Loading

PR Checklist

Please check if your PR fulfills the following requirements:

PR Type

What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • CI related changes
  • Documentation content changes
  • angular.dev application / infrastructure changes
  • Other... Please describe:

What is the new behavior?

Fixes #45033

This PR enhances Angular's extended diagnostics by adding documentation links to error messages, improving the developer experience when encountering template errors.

Benefits

  • Faster Problem Resolution: Developers can immediately access detailed explanations and examples

  • Self-Documenting Errors: Reduces the need to search external documentation

  • Consistent Experience: All extended diagnostics now provide uniform help resources

  • Educational Value: Helps developers understand Angular best practices

Impact

  • No breaking changes: Only enhances error messages

  • No performance impact: Changes are compile-time only

  • Improved DX: Better onboarding for developers learning Angular templates

Testing

  • Verified that diagnostic messages display correctly with new links

  • Confirmed that existing error examples and formatting are preserved

  • Ensured links point to valid Angular documentation URLs

Does this PR introduce a breaking change?

  • Yes
  • No

@pullapprove pullapprove bot requested a review from kirjs October 11, 2025 17:31
@angular-robot angular-robot bot added the detected: feature PR contains a feature commit label Oct 11, 2025
@JeanMeche
Copy link
Member

JeanMeche commented Oct 11, 2025

Can you also please add that it fixes #45033.

@JeanMeche
Copy link
Member

JeanMeche commented Oct 11, 2025

To fix the scope of the commit message should be compiler-cli instead of angular-cli.
Also if we make it a refactor(compiler-cli) instead of a feat(compiler-cli) we could land this improvement in a patc release. (feat commits can only land in the next major/minor release).

@JeanMeche
Copy link
Member

JeanMeche commented Oct 11, 2025

Also this change breaks some test, can you PTAL.

@SkyZeroZx
Copy link
Contributor

SkyZeroZx commented Oct 11, 2025

Looks interesting.
Could the same idea be considered for the rest of the Error Encyclopedia errors?
https://angular.dev/errors
It would be good to have the diagnostics sent to us in the reference documentation, like the Circular Dependency in DI case.
https://angular.dev/errors/NG0200.

Although I think it would be a PR with several commits on a PR to add it, I don't know what the team would think.

@JeanMeche
Copy link
Member

JeanMeche commented Oct 11, 2025 •
edited
Loading

Looks interesting.
Could the same idea be considered for the rest of the Error Encyclopedia errors?

We're already doing this for runtime errors (but only if the error actually has a doc entry. Those error are marked by a negative value)

example:

angular/packages/core/src/errors.ts

Lines 49 to 51 in e34776a

MULTIPLE_COMPONENTS_MATCH = -300,
EXPORT_NOT_FOUND = -301,
PIPE_NOT_FOUND = -302,

@SkyZeroZx
Copy link
Contributor

SkyZeroZx commented Oct 11, 2025

We're already doing this for runtime errors (but only if the error actually has a doc entry. Those error are marked by a negative value)

hadn’t noticed that the runtime errors were already being referenced.
So, are there any plans to include the remaining ones as well?

From what I see, for example, NG2009 belongs to the common package range according to the comment:

 * Error code ranges per package:
 *  - core : 100-999
 *  - forms: 1000-1999
 *  - common: 2000-2999
 *  - animations: 3000-3999
 *  - router: 4000-4999
 *  - platform-browser: 5000-5500
 */

@JeanMeche
Copy link
Member

JeanMeche commented Oct 11, 2025

That looks to be a bug in how we generate the error page. That's not a runtime error but a compiler error.
Probably an issue introduced by #59355.

@JeanMeche
Copy link
Member

JeanMeche commented Oct 11, 2025

Can you file an issue for that. On Angular.io we had a distinction between both type of errors. https://v17.angular.io/errors

@splincode splincode force-pushed the feat/improved-error-message branch from e82c9b2 to 46a98fa Compare October 12, 2025 10:24
@splincode splincode changed the title feat(angular-cli): improve diagnostic with help link refactor(compiler-cli): improve diagnostic with help link Oct 12, 2025
@angular-robot angular-robot bot added the area: compiler Issues related to `ngc`, Angular's template compiler label Oct 12, 2025
@ngbot ngbot bot added this to the Backlog milestone Oct 12, 2025
@splincode splincode force-pushed the feat/improved-error-message branch from 46a98fa to 2577c6d Compare October 14, 2025 20:03
JeanMeche
JeanMeche reviewed Oct 16, 2025
View reviewed changes
@splincode splincode force-pushed the feat/improved-error-message branch from 2577c6d to f17f3ed Compare October 16, 2025 10:35
@splincode splincode requested a review from JeanMeche October 16, 2025 10:35
@JeanMeche
Copy link
Member

JeanMeche commented Oct 16, 2025

Can you have a look at the failing tests ? Some expect to match the exact error message.
Also the lint check expects a body message of 20+ characters.

@splincode splincode force-pushed the feat/improved-error-message branch from f17f3ed to a599401 Compare October 16, 2025 18:51
@splincode splincode requested a review from JeanMeche October 16, 2025 18:53
@JeanMeche
Copy link
Member

JeanMeche commented Oct 16, 2025

Can you please rebase on main, it should fix the remaining broken test.

@splincode splincode force-pushed the feat/improved-error-message branch from a599401 to e30afcd Compare October 17, 2025 06:17
@splincode
Copy link
Contributor Author

splincode commented Oct 21, 2025

@JeanMeche Hello, is there anything else I should do?

@splincode splincode force-pushed the feat/improved-error-message branch from e30afcd to fed77ed Compare October 28, 2025 06:44
kirjs
kirjs requested changes Oct 28, 2025
View reviewed changes
Copy link
Contributor

@kirjs kirjs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Curious why didn't this break any tests?
Would be also nice to see formatExtendedError tested?

@splincode splincode force-pushed the feat/improved-error-message branch from fed77ed to d27a2fd Compare October 30, 2025 14:16
@splincode splincode requested review from JeanMeche and kirjs October 30, 2025 14:20
@splincode splincode force-pushed the feat/improved-error-message branch 2 times, most recently from 7ae4589 to 7f94841 Compare November 26, 2025 18:05
@splincode splincode requested a review from JeanMeche November 26, 2025 18:06
@JeanMeche
Copy link
Member

JeanMeche commented Dec 5, 2025

This change requires a cleanup on our side in Google's code base for us to be able to land it. We'll do it in due time aligned with our priorities.

@JeanMeche JeanMeche added the state: blocked on G3 cleanup This change requires a G3 cleanup label Dec 5, 2025
@splincode
Copy link
Contributor Author

splincode commented Dec 5, 2025

@JeanMeche Thank you very much

@JeanMeche JeanMeche modified the milestones: Backlog, v22 candidates Feb 12, 2026
@JeanMeche JeanMeche force-pushed the feat/improved-error-message branch from 7f94841 to 85073e3 Compare February 12, 2026 01:01
@splincode @JeanMeche
refactor(compiler-cli): improve diagnostic with help link
c63777e 
Add help link to extended template diagnostic messages to provide
users with additional guidance and documentation resources. This
enhancement improves developer experience by making it easier to
understand and resolve complex template issues through direct
access to relevant Angular documentation with detailed examples
and explanations for each diagnostic type.
@JeanMeche JeanMeche force-pushed the feat/improved-error-message branch from 85073e3 to c63777e Compare February 20, 2026 00:08
@JeanMeche
Copy link
Member

JeanMeche commented Feb 20, 2026 •
edited
Loading

TGP is "green"

This is good to go.

@JeanMeche JeanMeche requested review from kirjs and removed request for kirjs February 20, 2026 11:30
@JeanMeche JeanMeche added action: merge The PR is ready for merge by the caretaker target: patch This PR is targeted for the next patch release labels Feb 20, 2026
@ngbot
Copy link

ngbot bot commented Feb 20, 2026

I see that you just added the action: merge label, but the following checks are still failing:
    failure status "pullapprove" is failing
    pending forbidden labels detected: state: blocked
    pending 2 pending code reviews

If you want your PR to be merged, it has to pass all the CI checks.

If you can't get the PR to a green state due to flakes or broken main, please try rebasing to main and/or restarting the CI job. If that fails and you believe that the issue is not due to your change, please contact the caretaker and ask for help.

@JeanMeche JeanMeche removed the state: blocked on G3 cleanup This change requires a G3 cleanup label Feb 20, 2026
@thePunderWoman thePunderWoman merged commit 66b472e into angular:main Feb 20, 2026
28 of 29 checks passed
@thePunderWoman
Copy link
Contributor

thePunderWoman commented Feb 20, 2026

This PR was merged into the repository. The changes were merged into the following branches:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JeanMeche JeanMeche JeanMeche approved these changes

@kirjs kirjs kirjs approved these changes

Assignees

No one assigned

Labels

action: merge The PR is ready for merge by the caretaker area: compiler Issues related to `ngc`, Angular's template compiler detected: feature PR contains a feature commit target: patch This PR is targeted for the next patch release

Projects

None yet

Milestone

v22 candidates

Development

Successfully merging this pull request may close these issues.

Extended diagnostics should link to angular.dev documentation

5 participants

@splincode @JeanMeche @SkyZeroZx @thePunderWoman @kirjs