Empty & Error States

Designers spend weeks on the screen full of beautiful data. Then a real user signs up, opens Orders for the first time and sees… a white screen. Or a spinner that never stops. Or Error 500. The “nothing here” and “something broke” screens are often designed last, built in a hurry, and tested by nobody.

That makes them a gift for testers. Every list, feed, search and dashboard in an app has these states, and you can trigger most of them in a minute if you know how.

What are empty and error states?

An empty stateEmpty stateThe screen a user sees when there is no content yet, like an empty cart or no search results.Open in glossary → is what a screen shows when it has no content to display. An error state is what it shows when it couldn’t get or show the content. Together with the loading stateLoading stateWhat the UI shows while it waits for data or an action to finish, such as a spinner or skeleton.Open in glossary → and the normal data state, they make up the UI statesUI stateHow a component looks and behaves in a given situation: default, hover, pressed, focused, disabled, loading, error.Open in glossary → that every data screen must handle.

The key idea: “empty” and “failed” are different situations and need different messages. “You have no orders” and “We couldn’t load your orders” might both show an empty list, but they mean opposite things to the user.

The six types

Loading vs empty vs error

A screen that loads data goes through a few states. It should show exactly one at a time:

State	What it means	What the user should see
Loading	Request on its way	Skeleton or spinner, ideally in the same layout as the content
Data	Request OK, items returned	The content
Empty	Request OK, zero items	An empty state with a next step
Error	Request failed (offline, timeout, 500, 403)	An error state with a way to recover

Most bugs on these screens are mix-ups between these four: an empty list treated as “still loading” (endless spinner), an error treated as “empty” (the user thinks their data is gone), or “empty” shown for a moment before the data arrives.

Anatomy of a good one

A good empty or error state answers three questions: what happened, why, and what can I do now?

Designs & variants

Full-screen vs inline

Not every problem deserves a whole screen. Match the size of the message to the size of the problem.

Use a full-screen state when the screen’s main content is missing (the whole list failed, no permission, offline with no cached data). Use inline messages for one section, one card or one form field, and a banner for ongoing conditions like “You’re offline” while cached content stays visible.

Wording: say it like a human

The words matter as much as the picture. A good error messageError messageText that tells the user something went wrong and, ideally, how to fix it.Open in glossary → is specific, calm and useful:

Rules to test against:

• No raw codes or stack tracesStack traceThe list of function calls printed when an error happens, showing where in the code it occurred.Open in glossary →. “500”, “-1009” or “TypeError” mean nothing to users and can leak technical details to attackers. A short reference ID for support (“Ref: 8F3K”) is fine.
• No blame. “Invalid input” or “You did something wrong” for a server problem is both rude and false.
• Say whose problem it is. “Check your connection” (user can fix it) vs “This is on our side” (user should wait).
• Always a next step. Retry, Clear filters, Go to Home, Contact support. Never a dead end.
• Don’t lie. An error shown as “No orders yet” makes users think their data is gone.

Skeletons vs spinners

While data loads, a skeleton (grey shapes in the layout of the real content) feels faster and avoids layout jumps. A spinner is fine for short waits or small areas. Either way, test that the loading state ends: with data, with an empty state, or with an error. A loader that can spin forever is a bug.

Try it: state explorer

Here’s one Orders screen in seven states. Switch between them and compare the bad version (things testers report every week) with the good one. In the good version, Retry and Show all orders really work.

Screen state

LoadingDataEmpty: first useEmpty: filteredOfflineServer errorNo permission

How testers create it: Sign up with a fresh account that has never ordered.

Bad

Orders

AllActiveCanceled

No data

HomeSearchOrdersAccount

• "No data" is technical and cold
• No explanation and no next step
• Looks like an error

Good

Orders

AllActiveCanceled

No orders yet

When you order food, you'll find your orders and receipts here.

Browse restaurants

HomeSearchOrdersAccount

• Says what will appear here
• One clear action: Browse restaurants
• Friendly, not alarming

When to use it

Every screen that shows data needs an empty and an error state. Ask for them in reviews if the design only shows the “happy” screen. In particular:

• Lists, feeds and grids: orders, messages, favorites, notifications, search results.
• Screens behind an account or role: team data, admin pages, shared documents.
• Anything that needs the network: which is almost everything.
• Features that need a permission: camera, photos, location, contacts. If the user said no, explain why the feature needs it and how to turn it on in Settings.

Good and bad uses

Also don’t use a big empty-state illustration for tiny areas (an empty “Notes” field just needs placeholder text), and don’t use an error state for validation problems in a form: those belong next to the field (see Text field).

Common bugs

#	Bug	What you see	Typical severity
1	Endless spinner	Empty list or failed request, but the loader never stops	High
2	Dead-end error	“Something went wrong” with no Retry, no explanation, no way back	Medium–High
3	Retry is broken	Retry does nothing, or sends 2+ requests per tap (duplicate orders on POST!)	Medium–High
4	Raw technical error	TypeError, 500, null, undefined or a stack trace on screen	Medium
5	Empty flash	“No orders yet” appears for a moment before the data loads	Low–Medium
6	Error shown as empty	Offline, 403 or 500 shows “No orders yet”, so users think data was lost	High
7	Wrong empty message	Filtered list says “Place your first order” instead of “No results for this filter”	Low–Medium
8	Stale error	“You’re offline” stays after reconnecting, or the error stays after a successful retry	Medium
9	Two states at once	Data and the empty message both visible, or spinner on top of an error	Low–Medium
10	Silent for screen readers	Error appears but VoiceOver / TalkBack says nothing; focus stays on a removed button	High (for affected users)

Find the bug

This food delivery app’s Orders screen has six bugs. Use the device and proxy panel like a real tester:

• Watch the screen closely while it loads, then tap Refresh.
• Try each filter chip.
• Set Map Local to an empty list, then to a 500 error, and tap Refresh each time.
• Turn on Airplane mode, tap Refresh, turn it off again and tap Retry. Watch the network log.

🐞 Bug hunt: Orders screen

This demo has 6 hidden bugs. Explore it like a tester, then check your findings.

Found0/6

9:41

Orders

No orders yet

When you order food, you'll find your orders and receipts here.

Browse restaurants

HomeSearchOrdersAccount

Device & proxy

Restart app

Airplane modeMap Local /api/ordersOff (real server)200 · empty list []500 server error

Changes apply to the next request: tap Refresh in the app after changing them.

Network log

• Waiting for requests…

1. 1

   Hint: Set Map Local to "200 · empty list []" and tap Refresh.

   Endless spinner when there are no orders

   The API answers 200 with [], but the screen shows "Loading…" forever. The app only stops loading when items arrive. Expected: the first-use empty state ("No orders yet" with Browse restaurants).

   Reveal answer✓ I found this
2. 2

   Hint: Set Map Local to "500 server error" and tap Refresh.

   Server error is a dead end

   The screen says only "Something went wrong." No explanation, no Retry, no support link. Expected: a clear message ("We couldn't load your orders. This is on our side.") with a Retry button.

   Reveal answer✓ I found this
3. 3

   Hint: Go offline, Refresh, then tap Retry once and count the requests in the network log.

   Retry sends two requests per tap

   Every tap on Retry sends two GET /api/orders requests. Harmless-looking for a GET, but the same mistake on a POST (pay, order, send) creates duplicates. Expected: one request per tap, and the button is disabled while it runs.

   Reveal answer✓ I found this
4. 4

   Hint: Tap Refresh (or Restart app) and watch the first half second.

   Empty state flashes before the data loads

   “No orders yet” with Browse restaurants appears briefly, then a spinner, then the orders. A user with 4 orders sees a message saying they have none. Expected: loading state first, then the data; the empty state only when the API really returns no orders.

   Reveal answer✓ I found this
5. 5

   Hint: Turn Airplane mode on, then off, then load the orders again.

   Offline banner stays after reconnecting

   The “No internet connection” banner stays on screen even after the orders load successfully. Expected: the banner disappears as soon as the connection is back (and ideally the app reloads by itself).

   Reveal answer✓ I found this
6. 6

   Hint: Tap each filter chip.

   Raw TypeError on the Canceled filter

   There are no canceled orders, and instead of a friendly message the screen shows TypeError: Cannot read properties of undefined (reading 'map'). Expected: a filtered empty state like “No canceled orders” with a way back to All.

   Reveal answer✓ I found this

How to test it

How to create each state

You can’t wait for a real outage. Testers force these states on purpose:

Checklist

Empty & error state checklist

0 of 12 checked

Copy

• Every list screen has a designed first-use empty state with a clear next step
• An empty API response ([]) ends loading and shows the empty state, never an endless spinner
• The empty state never flashes before the real data loads
• Filtered / search "no results" says so and offers a way to clear the filter
• Offline shows a plain message (and cached data if available), and recovers by itself when back online
• Server errors (500, timeout, broken JSON) show a friendly message with a working Retry
• Retry sends exactly one request per tap and is disabled while it runs
• No permission (403 or a denied OS permission) is explained, not shown as "empty"
• No raw codes, stack traces, null or undefined on any screen
• Only one state is visible at a time (no data + empty message, no spinner over an error)
• Navigation stays usable on every empty and error screen
• Screen reader announces loading, empty and error states, and focus moves sensibly after Retry

Example test cases

Accessibility

• Announce state changes. When loading ends in an empty or error state, screen reader users must hear it. On iOS and Android, the app should post an accessibility announcement or move focus to the message.
  Dev note

  On the web, put the message in a live region (role="status" for empty, role="alert" for errors that need attention).
• Manage focus after Retry. The Retry button disappears when content loads. Focus should move to the content (or its heading), not get lost at the top of the page.
• The illustration is decorative. It should be hidden from screen readers. The text carries the meaning.
• Loading needs words too. A spinner should have an accessible label like “Loading orders”, and the skeleton itself should be hidden from screen readers.
• Don’t rely on color or icons alone. A red cloud icon without text tells a color-blind or blind user nothing.
• Contrast and text size. Grey “helper” text in empty states is often too light: it still needs 4.5:1, and must not be cut off at large text sizes.
• Buttons are real buttons with at least 44×44 pt / 48×48 dp touch targets and visible keyboard focus on the web.

Mobile vs web

iOSAndroidWeb

• Many apps follow the system layout for empty and “no results” states: icon, title, description, optional action.
  Dev note

  SwiftUI has a built-in ContentUnavailableView for them (iOS 17+).
• Test with airplane mode from Control Center, and with Low Data Mode and Wi-Fi with no internet.
• Check that denied permissions (Photos, Location) explain how to re-enable them in Settings, ideally with a button that opens the app’s settings page.
• Use the Network Link Conditioner (developer setting) for “100% Loss” and very slow profiles.

• Material guidance: keep empty states simple, with a short message and, where it helps, one action. Pull-to-refresh is a common recovery path, so test it on error screens too.
• Test with airplane mode, mobile data off for this app (per-app data restriction), and Data Saver.
• On the emulator, use the extended controls (Cellular settings) to simulate no signal or slow networks.
• Rotate the device and resize on tablets and foldables: the empty state should stay centered and readable.

• Use DevToolsDevToolsDeveloper tools built into browsers for inspecting pages, network traffic and errors.Open in glossary → → Network: Offline and throttling presets, Block request URL, and local overrides to return [] or a 500.
• Check the Console for errors while empty or error states show, and make sure nothing technical leaks into the page.
• Web apps can also show error pages (404, 500). Test a broken URL: is there a friendly page with a way back home, and the right HTTP status codeHTTP status codeA three-digit number in every server response: 200 means OK, 404 not found, 500 server error.Open in glossary →?
• Check the browser back button after an error: does it go somewhere sensible?

Check your understanding

Quick quiz

0/6 answered · 0 correct

1. 1.The API returns 200 with an empty list [], but the Orders screen keeps spinning. What kind of bug is this?

   AA server errorBThe empty state is not handled: the loading state never endsCA slow networkDA localization bug

2. 2.Which error message is best?

   A"Error 500"B"We couldn't load your orders. This is on our side. [Try again]"C"Invalid request. You did something wrong."D"TypeError: undefined"

3. 3.A team member without admin rights opens Team orders and sees "No orders yet", but the team has 40 orders. What is wrong?

   ANothing, they can't see them anywayBA permission error is shown as an empty state, so the user thinks data is missingCThe list needs a skeleton

4. 4.How can a tester make the Orders API return a 500 error on demand?

   AWait for the server to crashBUse a proxy tool (Map Local or a breakpoint) to replace the responseCTurn the phone off and onDAsk the user

5. 5.You reconnect after being offline, but the "You're offline" banner stays. What should you check next?

   AWhether the app recovers by itself or only after a restartBThe app iconCThe font sizeDNothing, it's cosmetic

6. 6.For a loading list, what is usually better than a blank screen?

   AA full-screen errorBA skeleton in the shape of the listCAn empty state that says "No orders yet"

Key takeaways

• Every data screen has four states: loading, data, empty and error. Exactly one should be visible at a time.
• Empty comes in types (first use, user cleared, no results, no permission), and errors in kinds (offline, server error, timeout). Each needs its own message.
• A good state says what happened, why, and what to do next, with a Retry or action that really works, and never shows raw codes or blames the user.
• Force the states yourself: fresh accounts, deleting everything, airplane mode, and proxy tools returning [], 500 or slow responses.
• Always test the way back: reconnect, retry, clear the filter, and check the screen fully recovers.