ioredis

Postconditions — what we check

• Redis · missing-error-listener

  error
  WhenRedis instance created without error event listener
  ThrowsErrors emitted as events, not exceptions - silent failures
  Required handlingCaller MUST attach an error listener immediately after creating Redis instance: `redis.on('error', (err) => logger.error(err))`. Without this listener, connection errors are silently logged to console and may crash the application.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Redis · connection-errors-not-handled

  error
  WhenConnection fails (ECONNREFUSED, ETIMEDOUT, ECONNRESET, ENOTFOUND, EPIPE, EAI_AGAIN)
  ThrowsError event emitted with connection error
  Required handlingCaller MUST handle connection errors in the error event listener. Common errors: ECONNREFUSED (Redis not running), ETIMEDOUT (network timeout), ECONNRESET (connection dropped), ENOTFOUND (DNS failure).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• get · unhandled-promise-rejection

  error
  WhenCommand promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning - will crash in future Node.js versions
  Required handlingCaller MUST use try-catch (async/await) or .catch() on all Redis commands. Commands return promises that may reject due to: connection errors, WRONGTYPE, timeout, or serialization failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• get · command-timeout

  warning
  WhenCommand exceeds timeout (default: no timeout)
  ThrowsMaxRetriesPerRequestError or CommandTimeoutError
  Required handlingCaller SHOULD set commandTimeout option to prevent hanging operations. Without timeout, commands may hang indefinitely on network issues.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• set · unhandled-promise-rejection

  error
  WhenCommand promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning
  Required handlingCaller MUST use try-catch or .catch() on all Redis commands.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• pipeline · pipeline-results-not-checked

  error
  WhenPipeline exec() results not checked for errors
  ThrowsIndividual command errors silently included in results array
  Required handlingCaller MUST check each result in pipeline.exec() return value. Format: [[null, 'OK'], [Error, undefined], ...]. Pipeline does NOT reject on individual command failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• pipeline · pipeline-exec-unhandled

  error
  WhenPipeline exec() promise rejected without catch
  ThrowsUnhandledPromiseRejectionWarning
  Required handlingCaller MUST use try-catch or .catch() on pipeline.exec().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• multi · watch-null-not-checked

  error
  WhenWATCH violation causes exec() to return null, not checked
  Throwsnull return value indicates transaction was aborted
  Required handlingCaller MUST check if exec() returns null after using WATCH. Null indicates a watched key was modified, transaction aborted. This is NOT an error/rejection - it's a null return value.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• multi · exec-abort-not-handled

  error
  WhenEXECABORT error in transaction not handled
  ThrowsEXECABORT error if queued command fails validation
  Required handlingCaller MUST check exec() results for EXECABORT errors. Happens when queued commands fail validation (WRONGTYPE, etc.).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• subscribe · subscriber-mode-violation

  error
  WhenNon-pub/sub commands used on subscriber connection
  ThrowsError: Connection in subscriber mode, only subscriber commands allowed
  Required handlingCaller MUST use separate Redis connection for pub/sub. After subscribe(), only subscribe/unsubscribe/psubscribe/punsubscribe/quit/ping allowed. Use redis.duplicate() to create separate connection for normal commands.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• brpop · blocking-without-timeout

  warning
  WhenBlocking command without timeout parameter
  ThrowsCommand may block indefinitely, causing resource leak
  Required handlingCaller SHOULD provide timeout parameter to blocking commands (BRPOP, BLPOP, BZPOPMIN, BZPOPMAX). Without timeout (or timeout=0), command blocks until data available, potentially forever. Recommended: Set reasonable timeout (e.g., 5-30 seconds).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• connect · connect-promise-unhandled

  error
  Whenconnect() promise rejected without catch
  ThrowsUnhandledPromiseRejectionWarning on connection failure
  Required handlingCaller MUST use try-catch or .catch() on explicit connect() calls.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• hget · wrong-type-error

  error
  WhenKey exists but is not a hash
  ThrowsReplyError with message containing 'WRONGTYPE'
  Required handlingCaller MUST catch WRONGTYPE errors for hash operations. This indicates key is not a hash - DO NOT retry. Fix data model or use correct command for key type.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• hget · unhandled-promise-rejection

  error
  WhenCommand promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning
  Required handlingCaller MUST use try-catch or .catch() on all Redis commands.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• hset · wrong-type-error

  error
  WhenKey exists but is not a hash
  ThrowsReplyError with message containing 'WRONGTYPE'
  Required handlingCaller MUST catch WRONGTYPE errors. Key exists with different type - DO NOT retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• hset · unhandled-promise-rejection

  error
  WhenCommand promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning
  Required handlingCaller MUST use try-catch or .catch() on all Redis commands.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• hgetall · wrong-type-error

  error
  WhenKey exists but is not a hash
  ThrowsReplyError with message containing 'WRONGTYPE'
  Required handlingCaller MUST catch WRONGTYPE errors. Key is not a hash - DO NOT retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• hgetall · unhandled-promise-rejection

  error
  WhenCommand promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning
  Required handlingCaller MUST use try-catch or .catch() on all Redis commands.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• lpush · wrong-type-error

  error
  WhenKey exists but is not a list
  ThrowsReplyError with message containing 'WRONGTYPE'
  Required handlingCaller MUST catch WRONGTYPE errors. Key exists with different type - DO NOT retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• lpush · unhandled-promise-rejection

  error
  WhenCommand promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning
  Required handlingCaller MUST use try-catch or .catch() on all Redis commands.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• rpush · wrong-type-error

  error
  WhenKey exists but is not a list
  ThrowsReplyError with message containing 'WRONGTYPE'
  Required handlingCaller MUST catch WRONGTYPE errors. Key exists with different type - DO NOT retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• rpush · unhandled-promise-rejection

  error
  WhenCommand promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning
  Required handlingCaller MUST use try-catch or .catch() on all Redis commands.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• publish · publish-error

  error
  WhenPublish fails (connection lost, etc.)
  ThrowsNetwork error or UnhandledPromiseRejectionWarning
  Required handlingCaller MUST catch publish errors with try-catch or .catch(). Network errors may be transient - implement retry logic. Returns number of subscribers that received the message (may be 0).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[13]
• eval · script-error

  error
  WhenLua script has syntax or runtime error
  ThrowsReplyError with script error details
  Required handlingCaller MUST catch Lua script errors. Script syntax errors should NOT be retried - fix script. Script runtime errors depend on logic - may or may not be retriable.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• eval · script-timeout

  error
  WhenLua script exceeds execution time limit
  ThrowsReplyError with timeout message
  Required handlingCaller MUST catch script timeout errors. Redis has lua-time-limit configuration (default 5 seconds). Optimize script or increase limit if needed. DO NOT retry immediately - may cause cascading timeouts.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• quit · quit-promise-unhandled

  error
  Whenquit() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning if connection already closed or network error
  Required handlingCaller MUST use try-catch or .catch() on quit(). quit() sends QUIT to server and waits for pending commands to complete. May reject if connection is already closed or broken before quit completes. Use disconnect() for immediate close if quit() is not available.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[14]
• quit · quit-pending-commands-lost

  warning
  Whenquit() called while commands are still queued
  ThrowsAbortError for queued commands that won't be executed
  Required handlingCaller MUST be aware that quit() waits for pending replies but new commands added after quit() is called will receive AbortError. Do not enqueue commands after calling quit(). Pattern: await all pending operations before calling quit() in shutdown handlers.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15]
• del · del-unhandled-promise-rejection

  error
  Whendel() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on del() calls. del() returns the count of deleted keys (0 if key doesn't exist — not an error). Returns Promise<number> — check return value only if you need to verify deletion.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• expire · expire-unhandled-promise-rejection

  error
  Whenexpire() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on expire() calls. expire() returns 1 if timeout was set, 0 if key doesn't exist — 0 is NOT an error. Silent expiry failures leave data in Redis indefinitely, causing memory leaks and stale data bugs in session management and rate limiting.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• expire · expire-returns-zero-not-checked

  warning
  Whenexpire() called on non-existent key and return value not checked
  ThrowsN/A (returns 0, not an error)
  Required handlingCaller SHOULD check expire() return value when setting TTL on critical keys. Returns 0 if key does not exist — the set+expire pattern can fail silently if the key was never written or was already deleted between set() and expire() calls. Use SET with EX option (atomic) instead of separate set()+expire() calls: `redis.set(key, value, 'EX', ttlSeconds)` to avoid the race condition.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• incr · incr-wrong-type-error

  error
  WhenKey exists but is not a string or integer
  ThrowsReplyError with 'ERR value is not an integer or out of range'
  Required handlingCaller MUST catch WRONGTYPE/value-not-integer errors. Happens when key holds a non-integer string (e.g., JSON blob) and incr() is called. This is a programming error — do NOT retry. Fix the data model.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17]
• incr · incr-unhandled-promise-rejection

  error
  Whenincr() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on incr() calls. Silent incr failures cause rate limiters to fail open (no limiting applied), which can lead to abuse, quota overruns, and billing errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• decr · decr-wrong-type-error

  error
  WhenKey exists but is not an integer, or decrement would go below -9223372036854775808
  ThrowsReplyError with 'ERR value is not an integer or out of range'
  Required handlingCaller MUST catch value-not-integer and overflow errors. Overflow at 64-bit integer minimum causes ReplyError — not silent wrap-around. Fix data model or use DECRBY with range validation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• decr · decr-unhandled-promise-rejection

  error
  Whendecr() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on decr() calls.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• zadd · zadd-wrong-type-error

  error
  WhenKey exists but is not a sorted set
  ThrowsReplyError with 'WRONGTYPE Operation against a key holding the wrong kind of value'
  Required handlingCaller MUST catch WRONGTYPE errors for sorted set operations. Key exists with different type — DO NOT retry. Fix data model.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• zadd · zadd-nan-score-error

  error
  WhenScore value is NaN
  ThrowsReplyError with 'not a float'
  Required handlingCaller MUST validate score before calling zadd(). NaN scores cause immediate ReplyError. Common when score comes from user input, division operations, or Date arithmetic. Validate: if (isNaN(score) || !isFinite(score)) throw before zadd().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]
• zadd · zadd-unhandled-promise-rejection

  error
  Whenzadd() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on zadd() calls.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• zrange · zrange-wrong-type-error

  error
  WhenKey exists but is not a sorted set
  ThrowsReplyError with 'WRONGTYPE Operation against a key holding the wrong kind of value'
  Required handlingCaller MUST catch WRONGTYPE errors. Key is not a sorted set — DO NOT retry. Fix data model.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• zrange · zrange-unhandled-promise-rejection

  error
  Whenzrange() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on zrange() calls. Returns empty array if key doesn't exist — not an error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• zrem · zrem-wrong-type-error

  error
  WhenKey exists but is not a sorted set
  ThrowsReplyError with 'WRONGTYPE Operation against a key holding the wrong kind of value'
  Required handlingCaller MUST catch WRONGTYPE errors. Returns 0 if member doesn't exist (not an error).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• zrem · zrem-unhandled-promise-rejection

  error
  Whenzrem() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on zrem() calls.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• sadd · sadd-wrong-type-error

  error
  WhenKey exists but is not a set
  ThrowsReplyError with 'WRONGTYPE Operation against a key holding the wrong kind of value'
  Required handlingCaller MUST catch WRONGTYPE errors for set operations. Key exists with different type — DO NOT retry. Fix data model.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• sadd · sadd-unhandled-promise-rejection

  error
  Whensadd() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on sadd() calls. Returns count of new members added (0 if already in set — not an error).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• smembers · smembers-wrong-type-error

  error
  WhenKey exists but is not a set
  ThrowsReplyError with 'WRONGTYPE Operation against a key holding the wrong kind of value'
  Required handlingCaller MUST catch WRONGTYPE errors. Returns empty array if key doesn't exist — not an error. For large sets, consider SSCAN instead to avoid blocking Redis.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• smembers · smembers-large-set-blocking

  warning
  WhenSet has thousands of members and smembers() is called in production
  ThrowsN/A — but Redis blocks for the duration, causing latency for all other clients
  Required handlingCaller SHOULD use sscanStream() for large sets instead of smembers(). smembers() returns ALL members in one blocking call. For sets > 1000 members, use cursor-based sscan() to avoid blocking Redis.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• smembers · smembers-unhandled-promise-rejection

  error
  Whensmembers() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on smembers() calls.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• srem · srem-wrong-type-error

  error
  WhenKey exists but is not a set
  ThrowsReplyError with 'WRONGTYPE Operation against a key holding the wrong kind of value'
  Required handlingCaller MUST catch WRONGTYPE errors. Returns 0 if member doesn't exist (not an error).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• srem · srem-unhandled-promise-rejection

  error
  Whensrem() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error
  Required handlingCaller MUST use try-catch or .catch() on srem() calls.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• blpop · blpop-blocking-without-timeout

  warning
  Whenblpop() called without timeout parameter or with timeout=0
  ThrowsCommand may block indefinitely, causing resource exhaustion
  Required handlingCaller SHOULD always provide a non-zero timeout to blpop(). With timeout=0, command blocks until data is available — may be indefinite. In SaaS apps, this can exhaust connection pool and cause other commands to queue. Recommended: use a reasonable timeout (5-30 seconds) and loop to re-poll. Pattern: while (running) { const result = await redis.blpop('queue', 5); ... }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• blpop · blpop-unhandled-promise-rejection

  error
  Whenblpop() promise rejected without catch handler
  ThrowsUnhandledPromiseRejectionWarning on connection error or MaxRetriesPerRequestError
  Required handlingCaller MUST use try-catch or .catch() on blpop() calls. Connection errors during blocking commands return MaxRetriesPerRequestError. Implement retry loop with backoff for job queue consumers.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• blpop · blpop-subscriber-mode-conflict

  error
  Whenblpop() called on a connection in subscriber mode
  ThrowsReplyError: Connection in subscriber mode, only subscriber commands allowed
  Required handlingCaller MUST NOT mix blpop() with pub/sub subscriptions on the same connection. Use a dedicated connection (redis.duplicate()) for job queue operations.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/redis/ioredishttps://github.com/redis/ioredis#error-handling
2. [2]github.com/redis/ioredishttps://github.com/redis/ioredis/issues/321
3. [3]github.com/redis/ioredishttps://github.com/redis/ioredis/issues/433
4. [4]github.com/redis/ioredishttps://github.com/redis/ioredis#command-timeout
5. [5]github.com/redis/ioredishttps://github.com/redis/ioredis#pipelines
6. [6]github.com/redis/ioredishttps://github.com/redis/ioredis/issues/753
7. [7]github.com/redis/ioredishttps://github.com/redis/ioredis/issues/883
8. [8]github.com/redis/ioredishttps://github.com/redis/ioredis#transactions
9. [9]github.com/redis/ioredishttps://github.com/redis/ioredis#pub/sub
10. [10]redis.io/commands/brpophttps://redis.io/commands/brpop/
11. [11]github.com/redis/ioredishttps://github.com/redis/ioredis#connect-to-redis
12. [12]redis.io/docs/latesthttps://redis.io/docs/latest/develop/clients/error-handling/
13. [13]dev.to/franciscomendes10866/using-redis-pub-sub-with-node-js-13k3https://dev.to/franciscomendes10866/using-redis-pub-sub-with-node-js-13k3
14. [14]github.com/redis/ioredishttps://github.com/redis/ioredis#connection-events
15. [15]github.com/redis/ioredishttps://github.com/redis/ioredis#basic-usage
16. [16]redis.io/commands/expirehttps://redis.io/commands/expire/
17. [17]redis.io/commands/incrhttps://redis.io/commands/incr/
18. [18]redis.io/commands/decrhttps://redis.io/commands/decr/
19. [19]redis.io/commands/zaddhttps://redis.io/commands/zadd/
20. [20]redis.io/commands/smembershttps://redis.io/commands/smembers/
21. [21]redis.io/commands/blpophttps://redis.io/commands/blpop/