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:

_tagCauseRetry?
RemoteReadError, RemoteQueryErrorServer Source failed or payload too bigRetry transient errors; shrink oversized ones
RemoteMutationErrorServer failed, refused, or 413 payloadRetry transient errors; fix refusals
UnreachableNetwork drop, timeout, or gateway 502Data.retry (automatic for durable writes)
RemoteLiveErrorLive stream disconnectedReconnects automatically; check liveStatus
RemoteProtocolErrorClient and server protocol mismatchDeploy matching versions
DecodeErrorResponse shape disagrees with SelectionAlign Selection and server schema
UnavailableServer omitted a selected fieldDrop field from Selection
OverlaidOverlay lacks an unfetched fieldOverlay every field read
UnauthenticatedMissing or expired sessionRetry after signing in
ForbiddenCaller lacks permissionRetry 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.