Learn / Errors and failures
Read failures
A read produces a RemoteData state: Initial, Loading, Ready, Refreshing, Failed { error, previous }, or NotFound. Use RemoteData.match for exhaustive handling or RemoteData.render for views. If a read stays Initial behind a spinner, call why(Data, model, read, { surfaces: actives }) to inspect which field or list is missing or blocked.
Every RemoteError has { _tag, message }, plus reason on auth/guard denials and refusal on declared write refusals:
_tag | Cause | Retry? |
|---|---|---|
RemoteReadError, RemoteQueryError | Server Source failed or payload too big | Retry transient errors; shrink oversized ones |
RemoteMutationError | Server failed, refused, or 413 payload | Retry transient errors; fix refusals |
Unreachable | Network drop, timeout, or gateway 502 | Data.retry (automatic for durable writes) |
RemoteLiveError | Live stream disconnected | Reconnects automatically; check liveStatus |
RemoteProtocolError | Client and server protocol mismatch | Deploy matching versions |
DecodeError | Response shape disagrees with Selection | Align Selection and server schema |
Unavailable | Server omitted a selected field | Drop field from Selection |
Overlaid | Overlay lacks an unfetched field | Overlay every field read |
Unauthenticated | Missing or expired session | Retry after signing in |
Forbidden | Caller lacks permission | Retry only under a different principal |
Failures propagate to every dependent read: a list fails when any row's required field fails, while rows still loading keep Refreshing so partial results stay visible.
A broken live stream keeps showing cached data, records a gap, and reconnects with backoff (liveStatus reads Reconnecting). If the server rejects the subscription query itself (RemoteLiveRefused, such as exceeding maxIdsPerEntity), liveStatus reads Refused until requirements change; see When a stream breaks.
Call Data.inspect(model).failures to view all active read failures alongside recorded diagnostics; see When a read fails for everything that clears a failure.