TencentCloud/TencentDB-Agent-Memory · error

redis config is required when state_backend=redis

Error message

redis config is required when state_backend=redis

What it means

createStateBackend validates that when config.type === 'redis' a `redis` config object is present. Without connection details (host/port/url etc.) a Redis backend cannot be constructed, so the factory fails fast with a clear message instead of an obscure connection error later.

Source

Thrown at MemoryCore/src/core/state/index.ts:52

    password?: string;
    /** database index (default: 0) */
    db?: number;
    keyPrefix?: string;
    consumerGroup?: string;
  };
}

/**
 * 工厂函数：根据配置创建对应的 State Backend。
 *
 * - type === "local": 内置 LocalStateBackend，零外部依赖
 * - remote backend: 动态加载远程状态后端实现；如果当前构建未包含，
 *   抛出明确错误。
 */
export async function createStateBackend(config: StateBackendConfig): Promise<IStateBackend> {
  if (config.type === "redis") {
    const redisCfg = config.redis;
    if (!redisCfg) throw new Error("redis config is required when state_backend=redis");

    let RedisStateBackendCtor: typeof import("../../integrations/redis/index.js").RedisStateBackend;
    try {
      ({ RedisStateBackend: RedisStateBackendCtor } = await import("../../integrations/redis/index.js"));
    } catch (err) {
      throw new Error(
        "[state-backend] Redis integration is not available — install or initialize " +
        "src/integrations/redis/ (private submodule) to use state_backend=redis, " +
        "or switch to state_backend=local. " +
        `Original error: ${err instanceof Error ? err.message : String(err)}`,
      );
    }

    // Dynamically import the remote backend client only when needed.
    const { default: Redis } = await import("ioredis");

    let client;
    if (redisCfg.url) {

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Add a redis section to the config, e.g. { type: 'redis', redis: { url: 'redis://localhost:6379' } }
2. Ensure the env var feeding the redis config (e.g. REDIS_URL/HOST/PORT) is set in the deployment environment
3. If redis is not intended, switch config.type to 'local'
4. Validate the config object before calling createStateBackend

Example fix

// before
createStateBackend({ type: 'redis' });
// after
createStateBackend({ type: 'redis', redis: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' } });

if (config.type === 'redis' && !config.redis) {
  throw new Error('state_backend=redis requires a redis config section');
}
await createStateBackend(config);

function hasRedisConfig(c) {
  return c.type !== 'redis' || (typeof c.redis === 'object' && c.redis !== null);
}

try {
  backend = await createStateBackend(config);
} catch (e) {
  if (e.message.includes('redis config is required')) {
    backend = await createStateBackend({ ...config, type: 'local' }); // fallback
  } else throw e;
}

When it happens

Trigger: Calling createStateBackend({ type: 'redis' }) — via startIntegratedServices or the `backend` helper — with the `redis` property omitted or set to null/undefined in StateBackendConfig.

Common situations: state_backend=redis set in a config file but the redis section not filled in; env-driven config where REDIS_URL was never set; copying a local-backend config and only flipping the type field.

Related errors

• [state-backend] Redis integration is not available — install
• invalid_param_value
• memory 系统用户 key 必须匹配 sk-mem-[A-Za-z0-9_-]{32}
• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式 llm.
• Generation log object key exceeds COS limit

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/947e50abc820828c. Report an issue: GitHub.