How to handle render errors
By default ISR does not cache a page whose server render produced an HTTP error. It falls back to client-side rendering so an error page never gets cached and served to every visitor. This recipe shows how to change that default and how to flag your own non-HTTP errors.
Why the default skips caching: an error render usually contains messages that should not be frozen into the cache. See How ISR works for where the cache decision happens.
Preconditions
- A working ISR setup with an
ISRHandlerinstance. - For custom errors: a component that renders on the server and can inject
IsrService.
Steps
-
Choose whether to cache pages that errored. The
skipCachingOnHttpErrorflag defaults totrue(skip caching). Set it tofalseonly if you deliberately want error responses cached.server.tsconst isr = new ISRHandler({// ...other configskipCachingOnHttpError: false,});cautionCaching error responses can serve broken content to every visitor. Only disable the skip if you handle those errors so the page stays functional.
-
Flag your own errors for cases HTTP status codes don't cover, such as a page that rendered successfully but has no content. Inject
IsrServiceand calladdError; a page with a recorded error is not cached and falls back to client-side rendering.posts.component.tsimport { Component, inject } from '@angular/core';import { IsrService } from '@rx-angular/isr/browser';@Component({selector: 'app-posts',standalone: true,template: '',})export class PostsComponent {private readonly isrService = inject(IsrService);private readonly postsService = inject(PostsService);loadPosts(): void {this.postsService.getPosts().subscribe((posts) => {if (posts.length === 0) {this.isrService.addError({name: 'No posts',message: 'There are no posts to show',} as Error);}});}}
Result
Pages that error during the server render are not cached and fall back to client-side rendering, unless you opted in via skipCachingOnHttpError: false. Pages you flag with addError are treated the same way. You can inspect recorded errors in the errors property embedded in the generated HTML.
See also
- Reference:
skipCachingOnHttpErrorfield onISRHandlerConfig - Reference:
IsrService.addError·IsrState