24 Jul 2024
2 min

retryWhen – RxJS Reference

retryWhen

Just as a plain observable retryWhen passes values along to the observer (mirroring) until an error in the source stream occurs. When that happens, the operator executes a callback function passing in the stream that will be emitting the errors starting with the current one that has just occurred. Regardless of the number of errors and retries, the callback function is only executed once.

The function is expected to return an observable that will be used as a guide to notify the operator when to retry the subscription to the original source observable. The operator subscribes to the returned guiding observable only once and doesn’t unsubscribe on future errors or until the original source observable completes. If that guiding observable calls complete or error then the retryWhen will send complete or error notification to the observer. Any other value emitted from the guiding observable will cause the operator to resubscribe to the original source observer.

retryWhen operator works in the following way:

  1. Subscribe to a source observable
  2. When a new value arrives from a source observable, send the value to the observer
  3. If the source observable throws an error, execute a callback function and subscribe to the returned guiding observable
  4. When a new value arrives from the guiding observable, re-subscribe to the original source
  5. If the guiding observable completes or throws an error, send the complete or error notification to the observer
  6. Once the source observable completes, send the complete notification to the observer

Usage

Errors in programs happen all the time and RxJS is no exception. For example, a network request can fail because of numerous reasons. It’s always useful to have a mechanism to retry an action.

For simple retries of network requests the retry operator is preferred. But when you need to retry based on some criteria, for example, an error description, you need to use retryWhen.

Here’s an example of using retryWhen to retry the request using information about the error:

const url = 'https://i.imgur.com/fHyEMsl.jpg';

fromFetch(url).pipe(
   switchMap((response) => response.json()),
   retryWhen((errors) => {
           return errors.pipe(
               takeWhile((error) => {
                   if (error instanceof SyntaxError) {
                       throw new Error(error.message);
                   }

                   return true;
               })
           );
       }
   )
).subscribe();

Playground

Additional resources

See also

Frequently asked questions

How does retryWhen work in RxJS?

retryWhen mirrors values from the source observable and, when an error occurs, calls your callback with an observable of errors. The callback returns a guiding observable, and each value it emits causes the operator to resubscribe to the source. Until then, values pass through to the observer unchanged, so retries stay invisible to downstream subscribers.

What is the difference between retry and retryWhen in RxJS?

Use retry for simple resubscription, as the article recommends for basic network request retries. Choose retryWhen when the retry decision depends on criteria such as an error description. Its callback receives the stream of errors and returns a guiding observable, and each value that observable emits triggers a resubscription to the source.

How do I retry an RxJS observable only for certain errors?

Inspect each error inside the guiding observable passed to retryWhen, typically with takeWhile() on the errors stream. The article's example checks whether the error is an instance of SyntaxError and throws a new Error with the same message when it is, which sends an error notification to the observer. Returning true for other errors keeps retries going.

How do I stop retrying with retryWhen in RxJS?

Make the guiding observable complete or error to stop retrying. If it completes or errors, retryWhen forwards that notification to the observer instead of resubscribing to the source. Any other emitted value triggers a resubscription. Once the source completes normally, the operator sends a complete notification to the observer.

Why is the retryWhen callback only executed once instead of on every error?

The callback passed to retryWhen runs only once, regardless of how many errors and retries occur. The guiding observable it returns is subscribed once and is not unsubscribed on future errors, staying active until the source completes. Design your error handling to process the whole error stream over time, for example with takeWhile() on the errors observable.

Share this post

Sign up for our newsletter

Stay up-to-date with the trends and be a part of a thriving community.