{"record":{"id":"947e50abc820828c","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"redis-config-is-required-when-state-backend-redis","errorCode":null,"errorMessage":"redis config is required when state_backend=redis","messagePattern":"redis config is required when state_backend=redis","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"MemoryCore/src/core/state/index.ts","lineNumber":52,"sourceCode":"    password?: string;\n    /** database index (default: 0) */\n    db?: number;\n    keyPrefix?: string;\n    consumerGroup?: string;\n  };\n}\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) {","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryCore/src/core/state/index.ts#L34-L70","documentation":"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.","triggerScenarios":"Calling createStateBackend({ type: 'redis' }) — via startIntegratedServices or the `backend` helper — with the `redis` property omitted or set to null/undefined in StateBackendConfig.","commonSituations":"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.","solutions":["Add a redis section to the config, e.g. { type: 'redis', redis: { url: 'redis://localhost:6379' } }","Ensure the env var feeding the redis config (e.g. REDIS_URL/HOST/PORT) is set in the deployment environment","If redis is not intended, switch config.type to 'local'","Validate the config object before calling createStateBackend"],"exampleFix":"// before\ncreateStateBackend({ type: 'redis' });\n// after\ncreateStateBackend({ type: 'redis', redis: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' } });","handlingStrategy":"validation","validationCode":"if (config.type === 'redis' && !config.redis) {\n  throw new Error('state_backend=redis requires a redis config section');\n}\nawait createStateBackend(config);","typeGuard":"function hasRedisConfig(c) {\n  return c.type !== 'redis' || (typeof c.redis === 'object' && c.redis !== null);\n}","tryCatchPattern":"try {\n  backend = await createStateBackend(config);\n} catch (e) {\n  if (e.message.includes('redis config is required')) {\n    backend = await createStateBackend({ ...config, type: 'local' }); // fallback\n  } else throw e;\n}","preventionTips":["Validate the full state backend config at startup with a schema (zod/ajv)","Fail fast in CI if state_backend=redis lacks redis settings","Document required env vars (REDIS_URL etc.) next to the config sample","Default to state_backend=local in dev when redis config is absent"],"tags":["config","redis","validation","missing-config"],"backgroundTag":"missing-configuration","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}