Postconditions: what we check

• get · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (for API errors) or Error (for network exhaustion)
  Required handlingCaller MUST wrap in try-catch. Uncaught UpstashError or network errors will propagate and crash the caller. Common API errors include: invalid auth token, quota exceeded, wrong key type. Network errors occur when Upstash is unreachable after the default 5 retry attempts.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• set · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (for API errors) or Error (for network exhaustion)
  Required handlingCaller MUST wrap in try-catch. UpstashError is thrown for API-level errors (e.g., wrong type for key) and network errors when Upstash is unreachable.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• del · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch. Even deletion can fail if the network is down or the auth token is invalid.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• mget · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch. Batch reads still fail atomically if the HTTP request fails.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• hget · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (including WRONGTYPE if key is not a hash) or Error
  Required handlingCaller MUST wrap in try-catch. UpstashError is thrown for wrong key type (e.g., key exists but is a string, not a hash) as well as network errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• hset · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (including WRONGTYPE if key is not a hash) or Error
  Required handlingCaller MUST wrap in try-catch. UpstashError for wrong type or auth errors; network error for connectivity failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• hgetall · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch. UpstashError includes WRONGTYPE errors; network errors when Upstash is unreachable.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• lpush · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (including WRONGTYPE if key is not a list) or Error
  Required handlingCaller MUST wrap in try-catch. WRONGTYPE error if key holds a different type.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• lrange · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• sadd · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (including WRONGTYPE if key is not a set) or Error
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• smembers · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• zadd · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (including WRONGTYPE if key is not a sorted set) or Error
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• zrange · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• expire · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• exists · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• incr · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error response
  ThrowsUpstashError (including WRONGTYPE if value is not an integer) or Error
  Required handlingCaller MUST wrap in try-catch. UpstashError if key holds a non-integer value.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• exec · network-or-api-error

  error
  Whennetwork failure after retries OR any pipeline command returns an error
  ThrowsUpstashError or Error — individual command errors throw UpstashError with message 'Command failed: <error>'
  Required handlingThe pipeline.exec() call MUST be wrapped in try-catch. The entire pipeline fails if the HTTP request fails or any batched command returns an error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• exec · pipeline-keep-errors-silent-failure

  error
  Whenpipeline built with pipeline({ keepErrors: true }) executes and individual commands fail
  Throwsdoes NOT throw — returns array of {error, result} objects; errors are silent if caller does not inspect each element
  Required handlingIf using pipeline({ keepErrors: true }), the returned array MUST be iterated and each element.error checked. Do NOT assume that a resolved promise means all commands succeeded. Pattern: results.forEach((r, i) => { if (r.error) handleError(r.error, commands[i]); });
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• subscribe · subscriber-error-not-thrown

  error
  Whensubscription fails or a message cannot be received (network error, auth failure, parse failure)
  Throwsdoes NOT throw to the calling context — errors are dispatched via Subscriber.on('error', handler) event
  Required handlingCallers MUST attach an error listener: subscriber.on('error', (err) => { ... }) before the subscription begins processing messages. This is not optional. Without it, network interruptions and auth failures are silently swallowed (or crash the process). Additionally attach a 'message' listener to receive data. subscribe() itself need not be awaited for error handling — the returned Subscriber object is the error surface.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• publish · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error (e.g., auth failure, quota exceeded)
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch. Log and alert on UpstashError — a publish failure means the message was not delivered to any subscriber.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• setex · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch. On UpstashError, the set did not occur — do not assume the value was stored.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• json.get · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error (invalid path syntax, wrong key type, auth failure)
  ThrowsUpstashError or Error — includes WRONGTYPE if key holds a non-JSON value
  Required handlingCaller MUST wrap in try-catch. Distinguish null return (key/path missing, handle gracefully) from thrown UpstashError (type mismatch, path error, network failure — handle as an error condition).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• json.set · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error (invalid path, non-JSON value, auth failure)
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch. On UpstashError, the write did not complete.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• rpush · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error (WRONGTYPE if key is not a list)
  ThrowsUpstashError (including WRONGTYPE) or Error
  Required handlingCaller MUST wrap in try-catch. WRONGTYPE indicates a data model bug (key reuse with different type) that should alert loudly. Network errors should trigger retry logic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• eval · script-error-or-network-failure

  error
  WhenLua script contains a runtime error OR network failure after retries OR auth failure
  ThrowsUpstashError — Lua errors are wrapped and re-thrown as UpstashError with the Lua error message
  Required handlingCaller MUST wrap in try-catch. Log UpstashError with the script context — Lua errors are often silent in development and only surface under specific data conditions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• evalsha · noscript-error

  error
  WhenSHA1 hash does not match any script loaded on the server (server restarted, wrong SHA)
  ThrowsUpstashError with NOSCRIPT error code — 'NOSCRIPT No matching script. Please use EVAL.'
  Required handlingCaller MUST catch UpstashError and check for NOSCRIPT in the message, then retry using eval() with the full Lua script source. Pattern: try { await redis.evalsha(sha, ...) } catch (e) { if (e instanceof UpstashError && e.message.includes('NOSCRIPT')) await redis.eval(script, ...); else throw e; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• evalsha · script-error-or-network-failure

  error
  WhenLua script contains a runtime error OR network failure after retries
  ThrowsUpstashError
  Required handlingCaller MUST wrap in try-catch for all error types beyond NOSCRIPT.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• incrbyfloat · wrongtype-or-not-float

  error
  Whenkey holds a non-numeric value OR key holds a value that cannot be represented as a float
  ThrowsUpstashError — Redis ERR value is not a valid float
  Required handlingCaller MUST wrap in try-catch. Validate that keys used with incrbyfloat are initialized to numeric strings. UpstashError indicates the key holds an incompatible value type.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• getdel · network-or-api-error

  error
  Whennetwork failure after retries OR Upstash API returns an error
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch. On UpstashError, the state of the key is unknown — implement a compensating read (GET) or require re-issuance of the token rather than assuming it was or was not consumed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• xadd · wrongtype-or-network-error

  error
  WhenKey exists but holds a non-stream type (WRONGTYPE error) OR network failure after retries OR auth failure OR MAXLEN/MINID approximate-trim eviction edge
  ThrowsUpstashError (including WRONGTYPE) or Error
  Required handlingCaller MUST wrap in try-catch. WRONGTYPE is a data-model bug — a non-stream key was reused as a stream — and should alert loudly because subsequent reads will also fail. Network errors during stream append in event-sourcing pipelines can cause lost events: callers MUST decide between (a) at-least-once with idempotent consumers, or (b) catching and queueing the entry locally before retry. Discarding the returned entry ID also discards the only handle that lets a consumer dedupe (use the returned ID, not a client-side ULID, for downstream correlation).
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2][3]
• xgroup · busygroup-or-nogroup-error

  error
  WhenCREATE called on an existing group (BUSYGROUP) OR DESTROY/SETID called on a non-existent group (NOGROUP) OR the target stream key does not exist and MKSTREAM was not supplied for CREATE
  ThrowsUpstashError — error messages include BUSYGROUP, NOGROUP, or 'ERR The XGROUP subcommand requires the key to exist.'
  Required handlingCaller MUST wrap in try-catch. BUSYGROUP on CREATE is benign during idempotent startup — match on `e.message.includes('BUSYGROUP')` and continue. NOGROUP on DESTROY/SETID indicates a configuration mismatch and should NOT be swallowed silently — log loudly so consumer rebalancing can detect missing groups. Pattern for idempotent consumer-group initialization: try { await redis.xgroup({ type: 'CREATE', key, group, id: '$', mkstream: true }); } catch (e) { if (e instanceof UpstashError && e.message.includes('BUSYGROUP')) { /* ok */ } else throw e; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][5]
• xreadgroup · nogroup-error

  error
  WhenThe named consumer group does not exist on the target stream (NOGROUP) OR the stream key does not exist OR network failure after retries
  ThrowsUpstashError — 'NOGROUP No such key ... or consumer group ...'
  Required handlingCaller MUST wrap in try-catch. NOGROUP commonly fires on cold-start before xgroup CREATE has run — handle it by creating the group (with MKSTREAM) and retrying once. Swallowing NOGROUP without re-creation silently halts every consumer in the group and the queue depth on the stream grows without bound (no visible error in metrics until a depth alert fires hours later).
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[6][7]
• copy · copy-result-not-checked

  warning
  Whenredis.copy(...) called without checking the returned "COPIED" | "NOT_COPIED" string union
  ThrowsDoes not throw on NOT_COPIED — silently returns the string literal. The caller assumes the copy succeeded when in fact the destination key was left untouched.
  Required handlingCaller MUST capture and branch on the return value. Pattern: const status = await redis.copy(src, dst); if (status === 'NOT_COPIED') { /* handle destination conflict */ } OR pass `{ replace: true }` if overwrite is the intent. Treating copy() as fire-and-forget produces stale/wrong reads from the destination key with no error signal.
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[8][9]
• copy · wrongtype-or-network-error

  error
  WhenSource key holds a type incompatible with the destination (rare) OR network failure after retries OR auth failure
  ThrowsUpstashError or Error
  Required handlingCaller MUST wrap in try-catch in addition to checking the return value. Network failures during copy leave the destination in an indeterminate state — implement a verifying read (GET on destination) before assuming success.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• flushdb · destructive-no-try-catch

  error
  Whenredis.flushdb() called without try-catch in production code paths
  ThrowsUpstashError on auth failure (NOAUTH) or permission denied (NOPERM in Redis ACL setups) or network failure after retries. Importantly, flushdb DOES succeed on the first call when permissions are granted — silently wiping every key.
  Required handlingCaller MUST wrap in try-catch AND wrap the call site in an explicit environment guard. Pattern: if (process.env.NODE_ENV !== 'test') throw new Error('flushdb in non-test env'); try { await redis.flushdb(); } catch (e) { log.error('flushdb failed', e); throw e; } A bare flushdb() with no try-catch is treated by reviewers as a destructive op with no logging, no audit trail, and no failure path — exactly the pattern that turns a config typo into a P0 outage. ACL-based auth errors (NOPERM) are silent when swallowed and mask permission-revocation rollouts.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10][11]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.