medusajs/medusa · critical · Error

[caching-redis] redisUrl is required

Error message

[caching-redis] redisUrl is required

What it means

The caching-redis module loader destructures redisUrl from its options and throws a plain Error if it is falsy. Without a connection string the Redis cache cannot be created, so the module fails at load time.

Source

Thrown at packages/modules/providers/caching-redis/src/loaders/connection.ts:39

): Promise<void> => {
  const logger_ = logger || console

  const moduleOptions = (options ??
    moduleDeclaration?.options ??
    {}) as RedisCacheModuleOptions

  const {
    redisUrl,
    redisOptions: newRedisOptions,
    // Module options, not ioredis options. Pulled out so they are not
    // forwarded to the client along with the deprecated top-level options.
    ttl: _ttl,
    prefix: _prefix,
    compressionThreshold: _compressionThreshold,
    ...deprecatedRedisOptions
  } = moduleOptions
  if (!redisUrl) {
    throw new Error("[caching-redis] redisUrl is required")
  }

  // Handle backward compatibility for deprecated options
  if (!newRedisOptions && Object.keys(deprecatedRedisOptions).length) {
    logger_.warn(
      "[caching-redis] Passing ioredis options at the top level of the module options is deprecated. Please use `redisOptions` instead for consistency with other modules."
    )
  }

  let redisClient: Redis

  const redisOptions: RedisOptions = {
    connectTimeout: 10000,
    commandTimeout: 5000,
    lazyConnect: true,
    maxRetriesPerRequest: 3,
    enableOfflineQueue: true,
    connectionName: "medusa-cache-redis",

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Add redisUrl (e.g. redis://default:password@host:6379) to the cacheModule options in medusa-config.js.
2. If using env vars, confirm REDIS_URL is exported where Medusa runs (docker-compose environment:, deploy secrets) and restart.
3. Prefer the redisOptions key for any ioredis extras — top-level ioredis options are deprecated and trigger an additional warning.

Example fix

// before
{ module: ModuleRegistrationKey.CACHE, resolve: "@medusajs/cache-redis", options: {} }
// after
{ module: ModuleRegistrationKey.CACHE, resolve: "@medusajs/cache-redis", options: { redisUrl: process.env.REDIS_URL } }

if (!process.env.REDIS_URL) {
  throw new Error("REDIS_URL must be set when using @medusajs/cache-redis")
}

const hasRedisUrl = (o: { redisUrl?: string } | undefined): o is { redisUrl: string } =>
  typeof o?.redisUrl === "string" && o.redisUrl.length > 0

When it happens

Trigger: Registering the Redis cache module in medusa-config.js without a redisUrl option, or with redisUrl: process.env.REDIS_URL where REDIS_URL is unset in that environment.

Common situations: REDIS_URL set locally but missing in the deployment/CI environment; renaming from the deprecated top-level ioredis options and forgetting the new key; the value lives in a .env file that isn't loaded (wrong cwd, docker env not passed).

Related errors

• OIDC engine requires a 'callback_url' option
• OIDC provider requires an 'issuer' option
• OIDC provider requires a 'client_id' option
• OIDC provider requires a 'callback_url' option
• OIDC '${label}' must be a valid URL

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/f73552031ab730b0. Report an issue: GitHub.