Skip to content

Partial failure in the UI

One part of a screen fails while the rest succeeds. Scope the failure to the part that failed, keep what already loaded, say what is missing and offer a retry for that piece, instead of blanking the page.

On this page

What it is

Partial failure is what happens when a screen built from several sources gets some of them and not others: the feed loads but the notification count times out, three pages of a list arrive and the fourth fails, or one field in a response errors while the rest resolve. The design question is how much of the screen one failure is allowed to take down. The weak default is all of it: one rejected promise, one thrown render or one failed request leaves a full-page error or a spinner that doesn't end. The stronger design draws a boundary around each independent region, so a failure stays inside the region it belongs to, the regions that succeeded stay on screen, and the failed one says what's missing and offers to try again.

Failures arrive at three layers, and each has its own containment tool. At the request layer, one of several requests fails: Promise.allSettled keeps the other requests' results. At the data layer, a response resolves but part of its payload is an error, which GraphQL permits when a resolver fails: the client's error policy decides whether the good fields are shown. At the render layer, a component throws while rendering: an error boundary swaps in a fallback for that subtree.

Promise.all rejects as soon as one input rejects, which fits tasks that depend on each other, but the combined promise then carries no aggregate value, so code that waits on it gets no array of results to render. Promise.allSettled waits for all of them and fulfills with an array of outcome objects, in the order the promises were passed, each marked fulfilled with a value or rejected with a reason. One caveat for screens: it settles when the slowest request settles, so a region that answered quickly waits for the others. When each region should paint as soon as its own data lands, give each region its own promise and its own state instead, and reserve allSettled for the case where you want one render with whatever arrived.

In React, a class component that defines static getDerivedStateFromError and componentDidCatch is an error boundary: React calls them when a component below it, at any depth, throws during rendering, and the boundary can update its state to show an error message and report the error to a logging service. The loading-side counterpart is Suspense: when a child suspends, the closest parent Suspense boundary shows its fallback, so nested boundaries let each region load and reveal on its own schedule rather than the whole page waiting on the slowest part. Both scope by placement: a boundary at the root turns a render error or a suspension anywhere below it into a full-page fallback; a boundary around each region contains it. Our advice: treat a failed request as state (loading, ok, error) and render the fallback from it; the boundary is for the throw you didn't plan for.

ts
type Section<T> =
  | { status: 'loading' }
  | { status: 'ok'; data: T }
  | { status: 'error'; error: unknown };

const sections: Record<string, Section<unknown>> = {};

function load(name: string, url: string) {
  sections[name] = { status: 'loading' };
  render();
  fetchJson(url)
    .then((data) => { sections[name] = { status: 'ok', data }; })
    .catch((error) => { sections[name] = { status: 'error', error }; })
    .finally(render);
}

// Each region starts on its own; none waits for the others.
load('feed', '/feed?limit=10');
load('sidebar', '/sidebar');
load('badge', '/notifications/count');

// The fallback's retry button reloads one region, not the page:
// <Sidebar section={sections.sidebar} onRetry={() => load('sidebar', '/sidebar')} />

When to use it

Screens made of independent regions: a home page with a feed, a sidebar and a badge count; a dashboard of widgets; a profile with a header, a post list and a follower list. Give each region its own request, its own loading state, its own error state and its own retry. The retry re-requests that region and nothing else, so a person who lost the sidebar doesn't lose their place in the feed to get it back.

Lists that load in pages. The weak treatment is to let a failed page replace the whole list with an error card. Keep the items already loaded, show an inline row where the next page would have appeared, and let its retry ask again for the same cursor, so a success continues from where the list stopped. New items arriving at the top of the list are a separate piece of state from the failed page at the bottom; one shouldn't reset the other.

ts
type Feed = {
  items: Post[];
  cursor: string | null;             // where the next page starts
  next: 'idle' | 'loading' | 'error';
};

async function loadNextPage(feed: Feed): Promise<Feed> {
  if (!feed.cursor || feed.next === 'loading') return feed;
  try {
    const page = await fetchJson(`/feed?after=${feed.cursor}`);
    return { items: [...feed.items, ...page.items], cursor: page.cursor, next: 'idle' };
  } catch {
    // items and cursor untouched: the inline retry asks for the same page
    return { ...feed, next: 'error' };
  }
}

Responses that are partly good. A GraphQL server that hits a resolver error can still return the fields that resolved, with the failure listed in an errors array beside data. In Apollo Client 4 the default error policy, none, puts the errors in error and sets data to undefined even when the server sent some; all populates both so you can render the good fields and a notice for the bad one; ignore renders the data as if nothing failed. Pick all when a view is still useful with a field missing, and show the gap rather than a silent null.

A refresh that fails when you already hold data. Keep the previous data on screen, mark it as not current with a short notice, and retry in the background. In React, if a tree that already shows content suspends again, its boundary shows the fallback again unless the update was started with startTransition or useDeferredValue, so wrap "load more" and refresh in a transition to keep the loaded content visible while the new request is in flight.

When not to

When the parts depend on each other. A checkout total, a permission check that gates everything below it, a chart whose series are read against each other: a partial result is wrong rather than merely incomplete. Promise.all is the better fit here, because rejecting on the first failure is the honest outcome, and the screen should show one clear error for the step with one retry.

When the failing part is the reason the page exists. An article page without the article, a watch page without the video: a per-region fallback around the body is a full-page error wearing a smaller frame. Make the error honest and full-size, keep the navigation working so the person can leave, and offer a retry. Scoping the failure helps when something else on the page is worth keeping.

When there are more boundaries than units of meaning. A screen where each small piece has its own spinner and its own error card flickers as pieces arrive and reads as broken even when nothing failed. Group pieces that a reader treats as one thing under one boundary. React reveals suspended content at most once per 300 ms and groups boundaries that become ready within that window, which softens the popcorn effect but doesn't remove the need to choose boundaries deliberately.

When the failure is about the session, not the region. An authentication failure on one request usually means the other requests will fail the same way; treat it as a page-level event (send the person to sign in, keep their draft) rather than a retry button in each widget.

Compared

ChoiceWhat it doesPick it whenThe other option is right when

Promise.allSettled instead of Promise.all

Waits for all the requests and reports each outcome in input order

Regions are independent and each can show its own result

The parts depend on each other: rejecting on the first failure is the honest result

A boundary per region instead of one at the root

A fallback replaces the subtree that threw or suspended, and nothing above it

The page stays useful with one region missing

The page is one thing, such as an article or a checkout step: one boundary, one clear error

Inline fallback instead of a full-page error

A short notice and a retry inside the region's own slot

The failed part is secondary and the rest already loaded

The failed part is the content the person came for

Render partial data (errorPolicy: 'all') instead of discarding it ('none')

Populates both data and error, so your code can render the resolved fields and the errors

A missing field degrades the view without making it wrong

A missing field would mislead, or you don't want nulls from errors in the cache

Keep stale data instead of clearing it

A failed refresh leaves the previous data visible with a notice

Older data is still useful, as in a feed or a dashboard

Older data can be acted on wrongly, as with a balance or a stock level

Hide the region instead of showing a fallback

The region disappears and the failure is logged

The region is decoration the person didn't ask for

The person expected the region or acted to load it, as with a next page

In a picture

Home screenFeed requestSidebar request

Step 1 of 4

Two regions, two requests

A home screen starts a request for the feed and one for the sidebar. Each has its own loading state, so neither waits for the other.

How to say it in an interview

The common mistake

Quiz

A home screen fires three independent requests with Promise.all and renders when it resolves. The notification count request rejects. What does the user see?
A list has forty items on screen. The request for the fifth page fails. Which treatment fits?
A GraphQL response carries data with one field null and an errors entry for that field. With Apollo Client 4 defaults, what does useQuery give you?
A checkout summary sums line items fetched from two services, and one request fails. Which design is better?

Questions that use this

Hear it in

Related

Sources

  1. MDN: Promise.allSettled()
  2. React reference: Component (componentDidCatch and error boundaries)
  3. React reference: Suspense
  4. Apollo Client 4 docs: Handling operation errors
Sign in to report a mistake