Errors

Every failure is a tagged error with a _tag you can match with Effect.catchTag. Most errors carry delivery, which says how far the command got. For how to handle them, see Errors and retries.

What does delivery mean?Copy Anchor Link

The package never replays a command after possibly-written or unknown.

SummaryCopy Anchor Link

RedisError is the union a command can fail with: AdmissionError, ConnectionError, HandshakeError, ProtocolError, ProfileError, CommandInputError, ServerError, ReplyError, SessionError, ClusterError, SentinelError, UnsupportedCommandError and UpstashError. Pipelines fail with BatchError, transactions with TransactionError, and typed keys with PayloadError.

ErrorsCopy Anchor Link

AdmissionErrorCopy Anchor Link

The connection refused to queue a command. count means the queued command limit is full, bytes means the queued byte budget is full, oversized means one command is larger than the budget allows, and session-required means the command needs a leased session and was sent on the shared connection. See limits and Sessions.

BatchErrorCopy Anchor Link

A pipeline or transaction ended without a clean result for every command. phase says where it stopped, execution says whether the commands ran, and outcomes holds one entry per command. outcomes is Redacted because replies can contain application data.

ClusterErrorCopy Anchor Link

A cluster routing failure, such as keys in different slots (cross-slot), a node that cannot be reached (node-unavailable) or too many redirects (redirect-limit). slot is present when a slot is known. See Cluster.

CommandInputErrorCopy Anchor Link

A command was rejected before it was sent because its arguments, options, metadata or routing were invalid. Always unsent.

ConnectionErrorCopy Anchor Link

The connection failed while a command was queued or in flight. generation identifies the physical connection. delivery is unsent if nothing was written and possibly-written if bytes may have reached the server. The package never retries a command after possibly-written.

CredentialErrorCopy Anchor Link

Credentials could not be configured, acquired or refreshed. cause is Redacted, and the error never carries a provider response, a token or a URL with credentials. See Credentials.

DiagnosticErrorCopy Anchor Link

A RedisMonitor stream failed. concurrent-consumer means a second consumer tried to read a stream that allows one.

HandshakeErrorCopy Anchor Link

Opening a connection failed during setup. stage names the step (auth, hello, name, database, role and others) and reason says how it failed. A server that rejects HELLO fails with stage: "hello" unless protocol is auto and the rejection is a known unsupported-protocol reply. Always unsent.

PayloadErrorCopy Anchor Link

A PayloadCodec could not encode a value before sending (encode) or decode bytes after receiving (decode). cause is Redacted. See Typed values.

ProfileErrorCopy Anchor Link

A deployment profile or network policy rejected the configuration or command before sending, for example a restricted command (restricted-command), an unsupported module (module) or a host outside the allow list (network-policy). Always unsent.

ProtocolErrorCopy Anchor Link

The RESP encoder or decoder rejected data. stage says whether this happened while validating config, encoding or decoding, and kind names the rule. offset is the byte position. limit and maximum name the limit that was exceeded, when there is one. See RESP2 and RESP3.

RedisConfigErrorCopy Anchor Link

A configuration value was invalid. field names the option and reason is a short message. The error never contains the rejected input.

ReplyErrorCopy Anchor Link

The server replied, but the reply did not have the shape the command expects. expected names the shape the decoder wanted, actual the received kind and path the position in a nested reply. Always replied.

SentinelErrorCopy Anchor Link

Sentinel discovery or routing failed. plane says whether the failure was on a Sentinel connection (sentinel) or a data node (data). See Sentinel.

ServerErrorCopy Anchor Link

The server answered with an error reply. code is the leading error word, such as WRONGTYPE, or ERR when the reply has none. reply holds the full reply as Redacted because the text can echo keys and values. Always replied.

SessionErrorCopy Anchor Link

A leased session or pool operation failed. pool-full means maxWaiters was reached, lease-timeout means no connection became free in time, and transaction-active means the session is inside a transaction. See Sessions.

StreamConsumerErrorCopy Anchor Link

A stream consumer could not continue. tombstone means a pending entry's payload was deleted or trimmed, acknowledgment-missing means XACK did not acknowledge the entry, and invalid-policy means the processing options were invalid. See Streams.

SubscriptionErrorCopy Anchor Link

A Pub/Sub or tracking subscription failed. delivery-gap means messages may have been lost across a reconnect, overflow means a buffer limit was reached and tracking-lost means client-side tracking was lost. generation identifies the physical connection. See Pub/Sub.

TransactionErrorCopy Anchor Link

A MULTI/EXEC transaction was rejected. queue-rejected means the server refused a queued command and exec-rejected means EXEC itself was refused. execution says whether the transaction ran (not-executed) or is unknown. errors is Redacted. See Transactions.

TransportErrorCopy Anchor Link

The socket layer failed. stage is open, read, write or close. Connection setup does not retry reason: "limit".

UnsupportedCommandErrorCopy Anchor Link

The executor cannot run this command. execution-mode means the command is not an ordinary command, such as a blocking one, and needs a session. explicit-node means the command targets a specific node, which a standalone executor cannot do. Always unsent.

UpstashErrorCopy Anchor Link

An Upstash HTTP request failed. stage says whether it failed in config, the request, the response or an event stream. status and retryAfterSeconds are set when the response carried them. delivery can be unknown because an HTTP request may have been processed even if no response arrived. See Upstash.