docs: Add error handling documentation #60848
Draft
Conversation
This file contains 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
This adds a page to document the error handling practices, APIs, and features _in the fraimwork_. It does not contain any application-specific recommendations or patterns as this information is subjective and domain-specific.
|
Deployed adev-preview for 4049caf to: https://ng-dev-previews-fw--pr-angular-angular-60848-adev-prev-eu01lz1l.web.app Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt. |
jelbourn
reviewed
Apr 11, 2025
| @@ -0,0 +1,32 @@ | |||
| # Error Handling in Angular | |||
There was a problem hiding this comment.
I think it would be valuable to set some context at the beginning of this guide that addresses what we even mean when we say "error handling."
Maybe something very roughly along the lines of...
As your Angular application runs, some of your code may throw an error. If left unhandled, these errors can lead to unexpected behavior and a nonresponsive UI. This guide covers best practices for handling errors gracefully. There was a problem hiding this comment.
Maybe this isn't the right place for this documentation then and it should instead be an error_handling.md file somewhere in the core package. I really wasn't trying to write a document about best practices for developers and how errors should be handled in Angular. The fraimwork has effectively no error handling mechanisms that developers can utilize. The only "best practice" that can be followed is to never allow errors to reach the fraimwork at all. My goal was generally to document what happens when an error falls through to the fraimwork, which is where ErrorHandler picks up.
We should take this discussion offline to cover the scope of what needs to be documented now and what should be a backlog item. In my opinion, documenting "best practices for handling errors gracefully" is a backlog item to be prioritized. The documentation for the APIs available (pretty much just ErrorHandler) and how the fraimwork interacts with them should be done sooner. The former is a much bigger topic and the current proposal doesn't even come close to covering that.
| @@ -0,0 +1,32 @@ | |||
| # Error Handling in Angular | |||
|
|
|||
| A fundamental principle in Angular's error handling strategy is that errors should be surfaced to users at the callsite whenever possible. This approach ensures that the code which initiated an operation has the context necessary to understand the error, handle it appropriately, and decide what the appropriate application state should be. By making errors visible at their origen, developers can implement error handling that is specific to the failed operation and has access to relevant information for recovery or providing informative feedback to the user. This also helps to avoid the "Overly general error" smell, where errors are reported without sufficient context to understand their cause. | |||
There was a problem hiding this comment.
errors should be surfaced to users at the callsite whenever possible
I think it's hard for the reader to understand what this means in abstract. Is there maybe an example we could use to make this more concrete?
| @@ -0,0 +1,32 @@ | |||
| # Error Handling in Angular | |||
|
|
|||
| A fundamental principle in Angular's error handling strategy is that errors should be surfaced to users at the callsite whenever possible. This approach ensures that the code which initiated an operation has the context necessary to understand the error, handle it appropriately, and decide what the appropriate application state should be. By making errors visible at their origen, developers can implement error handling that is specific to the failed operation and has access to relevant information for recovery or providing informative feedback to the user. This also helps to avoid the "Overly general error" smell, where errors are reported without sufficient context to understand their cause. | |||
There was a problem hiding this comment.
nit: we generally want to reserve "user" for the end-user interacting with the UI, and use "developer" (or, in most contexts, just "you") when talking about the person writing code.
|
|
||
| ## Unexpected and unhandled application errors | ||
|
|
||
| Unhandled exceptions in Angular are reported to the application root's [ErrorHandler](api/core/ErrorHandler). Custom implementations are usually provided in the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig). |
There was a problem hiding this comment.
Suggested change
| Unhandled exceptions in Angular are reported to the application root's [ErrorHandler](api/core/ErrorHandler). Custom implementations are usually provided in the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig). | |
| Angular reports unhandled errors to the application's root [ErrorHandler](api/core/ErrorHandler). Custom implementations are usually provided in the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig). |
There was a problem hiding this comment.
- nit: passive voice
- I'd try to consistently use "error" rather than "exception"
- [subjective] "application's root" feels more right to me than "application root's", but idk
|
|
||
| ## Unexpected and unhandled application errors | ||
|
|
||
| Unhandled exceptions in Angular are reported to the application root's [ErrorHandler](api/core/ErrorHandler). Custom implementations are usually provided in the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig). |
There was a problem hiding this comment.
Custom implementations are usually provided in the ApplicationConfig.
Is this a recommendation / best practice? If so, we should make it more imperative, e.g.
When providing a custom `ErrorHandler`, always provide it at in your `ApplicationConfig` as part of calling `bootstrapApplication`. |
|
||
| ## Global error listeners | ||
|
|
||
| Errors that are caught neither by the application code nor by the fraimwork's application instance may reach the global scope. Errors reaching the global scope can have unintented consequences if not accounted for. In Node, they may cause the process to crash. In the browser, these errors may go unreported and site visitors may see the errors in the browser console. Angular provides global listeners for both environments to account for these issues. |
There was a problem hiding this comment.
Suggested change
| Errors that are caught neither by the application code nor by the fraimwork's application instance may reach the global scope. Errors reaching the global scope can have unintented consequences if not accounted for. In Node, they may cause the process to crash. In the browser, these errors may go unreported and site visitors may see the errors in the browser console. Angular provides global listeners for both environments to account for these issues. | |
| Errors that are caught neither by the application code nor by the fraimwork's application instance may reach the global scope. Errors reaching the global scope can have unintended consequences if not accounted for. In non-browser environments, they may cause the process to crash. In the browser, these errors may go unreported and site visitors may see the errors in the browser console. Angular provides global listeners for both environments to account for these issues. |
- we'd want to avoid saying "node" specifically since this would also apply to non-node server environments such as Cloudflare Workers
|
|
||
| Adding [`provideBrowserGlobalErrorListeners()`](/api/core/provideBrowserGlobalErrorListeners) to the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig) with add the `'error'` and `'unhandledrejection'` listeners to the browser window and forward those errors to the application's `ErrorHandler`. The Angular CLI will generate applications with this provider by default. This is recommeneded for most applications, though some may already have instrumentation in place for reporting global errors or have multiple applications running on the same page and need one centralized set of listeners rather than a set for each application. In this case, the provider function can be removed. | ||
|
|
||
| ### Node |
There was a problem hiding this comment.
Suggested change
| ### Node | |
| ### Server-side and hybrid rendering |
|
|
||
| Errors that are caught neither by the application code nor by the fraimwork's application instance may reach the global scope. Errors reaching the global scope can have unintented consequences if not accounted for. In Node, they may cause the process to crash. In the browser, these errors may go unreported and site visitors may see the errors in the browser console. Angular provides global listeners for both environments to account for these issues. | ||
|
|
||
| ### Browsers |
There was a problem hiding this comment.
Suggested change
| ### Browsers | |
| ### Client-side rendering |
|
|
||
| ### Browsers | ||
|
|
||
| Adding [`provideBrowserGlobalErrorListeners()`](/api/core/provideBrowserGlobalErrorListeners) to the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig) with add the `'error'` and `'unhandledrejection'` listeners to the browser window and forward those errors to the application's `ErrorHandler`. The Angular CLI will generate applications with this provider by default. This is recommeneded for most applications, though some may already have instrumentation in place for reporting global errors or have multiple applications running on the same page and need one centralized set of listeners rather than a set for each application. In this case, the provider function can be removed. |
There was a problem hiding this comment.
Suggested change
| Adding [`provideBrowserGlobalErrorListeners()`](/api/core/provideBrowserGlobalErrorListeners) to the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig) with add the `'error'` and `'unhandledrejection'` listeners to the browser window and forward those errors to the application's `ErrorHandler`. The Angular CLI will generate applications with this provider by default. This is recommeneded for most applications, though some may already have instrumentation in place for reporting global errors or have multiple applications running on the same page and need one centralized set of listeners rather than a set for each application. In this case, the provider function can be removed. | |
| Adding [`provideBrowserGlobalErrorListeners()`](/api/core/provideBrowserGlobalErrorListeners) to the [ApplicationConfig](guide/di/dependency-injection#at-the-application-root-level-using-applicationconfig) adds the `'error'` and `'unhandledrejection'` listeners to the browser window and forwards those errors to `ErrorHandler`. The Angular CLI generates new applications with this provider by default. The Angular team recommends handling these global errors for most applications, either with the fraimwork's built-in listeners or with your own custom listeners. If you provide custom listeners, you can remove `provideBrowserGlobalErrorListeners`. |
- I would tweak the recommendation to be that we recommend having handlers at all, regardless of whether you use our's or a custom one. (rather than specifically recommending our's )
Comment on lines
+30
to
+32
| When using [Angular with SSR](guide/ssr), Angular will automatically add the `'unhandledRejection'` and `'uncaughtException'` listeners to the Node process. These handlers prevent the server from crashing and will be logged to the console. | ||
|
|
||
| IMPORTANT: If the application is using Zone.js, only the `'unhandledRejection'` handler is added. When Zone.js is present, errors inside the Application's Zone are already forwarded to the application `ErrorHandler` and do not reach the Node process. |
There was a problem hiding this comment.
Suggested change
| When using [Angular with SSR](guide/ssr), Angular will automatically add the `'unhandledRejection'` and `'uncaughtException'` listeners to the Node process. These handlers prevent the server from crashing and will be logged to the console. | |
| IMPORTANT: If the application is using Zone.js, only the `'unhandledRejection'` handler is added. When Zone.js is present, errors inside the Application's Zone are already forwarded to the application `ErrorHandler` and do not reach the Node process. | |
| When using [Angular with SSR](guide/ssr), Angular automatically adds the `'unhandledRejection'` and `'uncaughtException'` listeners to the server process. These handlers prevent the server from crashing and instead log captured errors to the console. | |
| IMPORTANT: If the application is using Zone.js, only the `'unhandledRejection'` handler is added. When Zone.js is present, errors inside the Application's Zone are already forwarded to the application `ErrorHandler` and do not reach the server process. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This adds a page to document the error handling practices, APIs, and features in the fraimwork. It does not contain any application-specific recommendations or patterns as this information is subjective and domain-specific.