ioredis

Property	Value
Package	ioredis
Versions Covered	>=4.27.8
Contract Version	1.0.0
Status	production
Last Verified	2026-02-27
Maintainer	corpus-team

Installation

npm install ioredis

Covered Functions

This contract covers 15 function(s):

Redis()

Redis client constructor - Creates a Redis connection instance

Import:

import { Redis } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - missing-error-listener

Condition: Redis instance created without error event listener

Throws: Errors emitted as events, not exceptions - silent failures

Required Handling:

Caller 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.

📖 Source

🔴 ERROR - connection-errors-not-handled

Condition: Connection fails (ECONNREFUSED, ETIMEDOUT, ECONNRESET, ENOTFOUND, EPIPE, EAI_AGAIN)

Throws: Error event emitted with connection error

Required Handling:

Caller MUST handle connection errors in the error event listener. Common errors: ECONNREFUSED (Redis not running), ETIMEDOUT (network timeout), ECONNRESET (connection dropped), ENOTFOUND (DNS failure).

📖 Source

Edge Cases

Known gotchas and sharp edges:

ℹ️ INFO - lazy-connection

Connection is lazy by default - errors may occur after constructor returns

📖 Source

---

get()

Get value of key from Redis

Import:

import { get } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - unhandled-promise-rejection

Condition: Command promise rejected without catch handler

Throws: UnhandledPromiseRejectionWarning - will crash in future Node.js versions

Required Handling:

Caller 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.

📖 Source

⚠️ WARNING - command-timeout

Condition: Command exceeds timeout (default: no timeout)

Throws: MaxRetriesPerRequestError or CommandTimeoutError

Required Handling:

Caller SHOULD set commandTimeout option to prevent hanging operations. Without timeout, commands may hang indefinitely on network issues.

📖 Source

---

set()

Set key to value in Redis

Import:

import { set } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - unhandled-promise-rejection

Condition: Command promise rejected without catch handler

Throws: UnhandledPromiseRejectionWarning

Required Handling:

Caller MUST use try-catch or .catch() on all Redis commands.

📖 Source

---

pipeline()

Create pipeline for batch command execution

Import:

import { pipeline } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - pipeline-results-not-checked

Condition: Pipeline exec() results not checked for errors

Throws: Individual command errors silently included in results array

Required Handling:

Caller MUST check each result in pipeline.exec() return value. Format: [[null, 'OK'], [Error, undefined], ...]. Pipeline does NOT reject on individual command failures.

📖 Source

🔴 ERROR - pipeline-exec-unhandled

Condition: Pipeline exec() promise rejected without catch

Throws: UnhandledPromiseRejectionWarning

Required Handling:

Caller MUST use try-catch or .catch() on pipeline.exec().

📖 Source

---

multi()

Create transaction (MULTI/EXEC block)

Import:

import { multi } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - watch-null-not-checked

Condition: WATCH violation causes exec() to return null, not checked

Throws: null return value indicates transaction was aborted

Required Handling:

Caller 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.

📖 Source

🔴 ERROR - exec-abort-not-handled

Condition: EXECABORT error in transaction not handled

Throws: EXECABORT error if queued command fails validation

Required Handling:

Caller MUST check exec() results for EXECABORT errors. Happens when queued commands fail validation (WRONGTYPE, etc.).

📖 Source

---

subscribe()

Subscribe to Redis pub/sub channel

Import:

import { subscribe } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - subscriber-mode-violation

Condition: Non-pub/sub commands used on subscriber connection

Throws: Error: Connection in subscriber mode, only subscriber commands allowed

Required Handling:

Caller 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.

📖 Source

Edge Cases

Known gotchas and sharp edges:

ℹ️ INFO - duplicate-for-commands

Must use redis.duplicate() to create separate connection for normal commands while subscribed

📖 Source

---

brpop()

Blocking pop from list (right side)

Import:

import { brpop } from 'ioredis';

Postconditions

What happens after calling this function:

⚠️ WARNING - blocking-without-timeout

Condition: Blocking command without timeout parameter

Throws: Command may block indefinitely, causing resource leak

Required Handling:

Caller 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).

📖 Source

---

connect()

Explicitly connect to Redis (usually automatic)

Import:

import { connect } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - connect-promise-unhandled

Condition: connect() promise rejected without catch

Throws: UnhandledPromiseRejectionWarning on connection failure

Required Handling:

Caller MUST use try-catch or .catch() on explicit connect() calls.

📖 Source

---

hget()

Get hash field value

Import:

import { hget } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - wrong-type-error

Condition: Key exists but is not a hash

Throws: ReplyError with message containing 'WRONGTYPE'

Required Handling:

Caller 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.

📖 Source

🔴 ERROR - unhandled-promise-rejection

Condition: Command promise rejected without catch handler

Throws: UnhandledPromiseRejectionWarning

Required Handling:

Caller MUST use try-catch or .catch() on all Redis commands.

📖 Source

---

hset()

Set hash field value

Import:

import { hset } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - wrong-type-error

Condition: Key exists but is not a hash

Throws: ReplyError with message containing 'WRONGTYPE'

Required Handling:

Caller MUST catch WRONGTYPE errors. Key exists with different type - DO NOT retry.

📖 Source

🔴 ERROR - unhandled-promise-rejection

Condition: Command promise rejected without catch handler

Throws: UnhandledPromiseRejectionWarning

Required Handling:

Caller MUST use try-catch or .catch() on all Redis commands.

📖 Source

---

hgetall()

Get all hash fields and values

Import:

import { hgetall } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - wrong-type-error

Condition: Key exists but is not a hash

Throws: ReplyError with message containing 'WRONGTYPE'

Required Handling:

Caller MUST catch WRONGTYPE errors. Key is not a hash - DO NOT retry.

📖 Source

🔴 ERROR - unhandled-promise-rejection

Condition: Command promise rejected without catch handler

Throws: UnhandledPromiseRejectionWarning

Required Handling:

Caller MUST use try-catch or .catch() on all Redis commands.

📖 Source

---

lpush()

Push value to head of list

Import:

import { lpush } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - wrong-type-error

Condition: Key exists but is not a list

Throws: ReplyError with message containing 'WRONGTYPE'

Required Handling:

Caller MUST catch WRONGTYPE errors. Key exists with different type - DO NOT retry.

📖 Source

🔴 ERROR - unhandled-promise-rejection

Condition: Command promise rejected without catch handler

Throws: UnhandledPromiseRejectionWarning

Required Handling:

Caller MUST use try-catch or .catch() on all Redis commands.

📖 Source

---

rpush()

Push value to tail of list

Import:

import { rpush } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - wrong-type-error

Condition: Key exists but is not a list

Throws: ReplyError with message containing 'WRONGTYPE'

Required Handling:

Caller MUST catch WRONGTYPE errors. Key exists with different type - DO NOT retry.

📖 Source

🔴 ERROR - unhandled-promise-rejection

Condition: Command promise rejected without catch handler

Throws: UnhandledPromiseRejectionWarning

Required Handling:

Caller MUST use try-catch or .catch() on all Redis commands.

📖 Source

---

publish()

Publish message to Redis channel

Import:

import { publish } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - publish-error

Condition: Publish fails (connection lost, etc.)

Throws: Network error or UnhandledPromiseRejectionWarning

Required Handling:

Caller 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).

📖 Source

---

eval()

Execute Lua script on Redis server

Import:

import { eval } from 'ioredis';

Postconditions

What happens after calling this function:

🔴 ERROR - script-error

Condition: Lua script has syntax or runtime error

Throws: ReplyError with script error details

Required Handling:

Caller 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.

📖 Source

🔴 ERROR - script-timeout

Condition: Lua script exceeds execution time limit

Throws: ReplyError with timeout message

Required Handling:

Caller 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.

📖 Source

---

Example: Proper Error Handling

import ioredis from 'ioredis';

async function example() {
  try {
    const result = await Redis(/* args */);
    // Handle success
    return result;
  } catch (error) {
    // Handle error according to contract postconditions
    console.error('Error:', error);
    throw error;
  }
}

See Also

• Contract Schema Reference
• All Supported Packages
• How to Use verify-cli