TencentCloud/TencentDB-Agent-Memory · error

[state-backend] Redis integration is not available — install

Error message

[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)}

What it means

createStateBackend dynamically imports the RedisStateBackend from src/integrations/redis/ (a private submodule). If that import fails — submodule not installed/initialized — it throws this descriptive error wrapping the original import error, and suggests switching to the local backend.

Source

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

}

/**
 * 工厂函数：根据配置创建对应的 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) {
      client = new Redis(redisCfg.url);
    } else {
      client = new Redis({
        host: redisCfg.host ?? "127.0.0.1",
        port: redisCfg.port ?? 6379,
        password: redisCfg.password,

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Run `git submodule update --init --recursive` (and authenticate for the private repo) to install src/integrations/redis/
2. Rebuild/repackage the artifact including the redis integration module
3. Temporarily set state_backend=local if Redis is not required in this environment
4. Inspect the wrapped 'Original error' in the message for the underlying import failure cause

Example fix

# before
node dist/main.js  // throws: Redis integration is not available...
# after
git submodule update --init --recursive && npm run build && node dist/main.js

import { existsSync } from 'fs';
const redisAvailable = existsSync('src/integrations/redis/index.ts') || existsSync('dist/integrations/redis/index.js');
if (!redisAvailable && config.type === 'redis') config = { ...config, type: 'local' };

try {
  backend = await createStateBackend({ type: 'redis', redis: redisCfg });
} catch (e) {
  if (String(e.message).includes('Redis integration is not available')) {
    console.warn('Redis integration missing; falling back to local backend');
    backend = await createStateBackend({ type: 'local' });
  } else throw e;
}

When it happens

Trigger: config.type === 'redis' with a valid redis config, but the dynamic import of ../../integrations/redis/index.js throws because the private submodule is absent, empty, or fails to initialize in the current build.

Common situations: Fresh clone without git submodule init/update; Docker image built without the private submodule credentials; CI checkout without submodules; deployment artifact that strips integrations/.

Related errors

• redis config is required when state_backend=redis
• invalid_param_value
• unknown_module
• invalid_param_scope
• Invalid scrypt parameter: ${raw}

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