{"record":{"id":"dbda8b0f78dbeb57","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"state-backend-redis-integration-is-not-available","errorCode":null,"errorMessage":"[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)}","messagePattern":"\\[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: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"MemoryCore/src/core/state/index.ts","lineNumber":58,"sourceCode":"}\n\n/**\n * 工厂函数：根据配置创建对应的 State Backend。\n *\n * - type === \"local\": 内置 LocalStateBackend，零外部依赖\n * - remote backend: 动态加载远程状态后端实现；如果当前构建未包含，\n *   抛出明确错误。\n */\nexport async function createStateBackend(config: StateBackendConfig): Promise<IStateBackend> {\n  if (config.type === \"redis\") {\n    const redisCfg = config.redis;\n    if (!redisCfg) throw new Error(\"redis config is required when state_backend=redis\");\n\n    let RedisStateBackendCtor: typeof import(\"../../integrations/redis/index.js\").RedisStateBackend;\n    try {\n      ({ RedisStateBackend: RedisStateBackendCtor } = await import(\"../../integrations/redis/index.js\"));\n    } catch (err) {\n      throw new Error(\n        \"[state-backend] Redis integration is not available — install or initialize \" +\n        \"src/integrations/redis/ (private submodule) to use state_backend=redis, \" +\n        \"or switch to state_backend=local. \" +\n        `Original error: ${err instanceof Error ? err.message : String(err)}`,\n      );\n    }\n\n    // Dynamically import the remote backend client only when needed.\n    const { default: Redis } = await import(\"ioredis\");\n\n    let client;\n    if (redisCfg.url) {\n      client = new Redis(redisCfg.url);\n    } else {\n      client = new Redis({\n        host: redisCfg.host ?? \"127.0.0.1\",\n        port: redisCfg.port ?? 6379,\n        password: redisCfg.password,","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryCore/src/core/state/index.ts#L40-L76","documentation":"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.","triggerScenarios":"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.","commonSituations":"Fresh clone without git submodule init/update; Docker image built without the private submodule credentials; CI checkout without submodules; deployment artifact that strips integrations/.","solutions":["Run `git submodule update --init --recursive` (and authenticate for the private repo) to install src/integrations/redis/","Rebuild/repackage the artifact including the redis integration module","Temporarily set state_backend=local if Redis is not required in this environment","Inspect the wrapped 'Original error' in the message for the underlying import failure cause"],"exampleFix":"# before\nnode dist/main.js  // throws: Redis integration is not available...\n# after\ngit submodule update --init --recursive && npm run build && node dist/main.js","handlingStrategy":"fallback","validationCode":"import { existsSync } from 'fs';\nconst redisAvailable = existsSync('src/integrations/redis/index.ts') || existsSync('dist/integrations/redis/index.js');\nif (!redisAvailable && config.type === 'redis') config = { ...config, type: 'local' };","typeGuard":null,"tryCatchPattern":"try {\n  backend = await createStateBackend({ type: 'redis', redis: redisCfg });\n} catch (e) {\n  if (String(e.message).includes('Redis integration is not available')) {\n    console.warn('Redis integration missing; falling back to local backend');\n    backend = await createStateBackend({ type: 'local' });\n  } else throw e;\n}","preventionTips":["Initialize git submodules in CI/Dockerfile: git submodule update --init --recursive","Add a startup health check that verifies the redis integration module resolves","Keep local backend as a documented fallback for builds without the private submodule","Log the wrapped 'Original error' to diagnose the actual import failure"],"tags":["redis","missing-module","submodule","config"],"backgroundTag":"missing-module","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}