{"record":{"id":"8beeeec685ad2b71","repo":"redis/node-redis","slug":"unknown-request-policy-requestpolicy","errorCode":null,"errorMessage":"Unknown request policy ${requestPolicy}","messagePattern":"Unknown request policy (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/index.ts","lineNumber":570,"sourceCode":"    const responsePolicy = policy.response;\n\n    // Fast path: default-keyed request + response — the overwhelming majority\n    // of traffic (every single-key command). Route by firstKey and pass the\n    // sole reply through, skipping the plan/reducer/post-reply machinery,\n    // which is a no-op for this shape (the hooks only concern\n    // FT.AGGREGATE/FT.CURSOR/SCAN and the remap only numeric aggregates —\n    // none of them default-keyed).\n    if (\n      requestPolicy === REQUEST_POLICIES_WITH_DEFAULTS.DEFAULT_KEYED &&\n      responsePolicy === RESPONSE_POLICIES_WITH_DEFAULTS.DEFAULT_KEYED\n    ) {\n      return this._execute(parser, readonly, options, makeFn(parser));\n    }\n\n    // https://redis.io/docs/latest/develop/reference/command-tips\n    const router = REQUEST_ROUTERS[requestPolicy];\n    if (!router) {\n      throw new Error(`Unknown request policy ${requestPolicy}`);\n    }\n    // Validated before any per-node promise is dispatched — throwing after\n    // would orphan in-flight rejections (unhandled-rejection noise) and run\n    // side effects for a reply that can never be reduced.\n    const reducer = RESPONSE_REDUCERS[responsePolicy];\n    if (!reducer) {\n      throw new Error(`Unknown response policy ${responsePolicy}`);\n    }\n    // Routers are typed against the erased base cluster types (routing is\n    // below the typed command surface); bridge this instantiation's slots in.\n    const plan = await router(\n      this._slots as unknown as Parameters<typeof router>[0],\n      parser,\n      readonly,\n      policy.keySpecs\n    );\n\n    if (plan.length === 0) {","sourceCodeStart":552,"sourceCodeEnd":588,"githubUrl":"https://github.com/redis/node-redis/blob/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/index.ts#L552-L588","documentation":"Thrown in the cluster command dispatch when a command's resolved request policy is not present in the REQUEST_ROUTERS registry. The fast path (DEFAULT_KEYED) is handled earlier; this branch covers fan-out policies. An unknown policy means the command metadata or a custom command definition specified a request policy the cluster router does not know how to dispatch.","triggerScenarios":"Defining a custom command (via sendCommand or a script) whose command metadata sets a request value not in REQUEST_POLICIES_WITH_DEFAULTS. A version mismatch where command metadata references a policy added in a newer release. Internal corruption of the policy registry.","commonSituations":"Using custom/script commands with manually-set policies that are misspelled or unsupported; running a command whose policy table entry was added after the installed library version; monkeypatching command metadata with an invalid request value.","solutions":["For custom commands, use a supported request policy (DEFAULT_KEYED, DEFAULT_KEYLESS, MULTI_SHARD, ALL_SHARDS, ALL_NODES, SPECIAL) or omit policy to get the default.","Upgrade node-redis to a version whose policy table matches the command metadata you are using.","Audit any code that sets command metadata .request to ensure it uses a value from REQUEST_POLICIES_WITH_DEFAULTS.","Report with the command name and the resolved requestPolicy value if it occurs on a built-in command."],"exampleFix":"// before (custom command metadata with bad policy)\n{ REQUEST_POLICY: 'shard' /* misspelled, not in registry */ }\n\n// after\n{ REQUEST_POLICY: 'multi_shard' } // valid registry value","handlingStrategy":"validation","validationCode":"import { REQUEST_POLICIES_WITH_DEFAULTS } from '@redis/client';\nfunction isValidRequestPolicy(p: string): boolean {\n  return Object.values(REQUEST_POLICIES_WITH_DEFAULTS).includes(p as never);\n}\nisValidRequestPolicy(metadata.request);","typeGuard":"function isKnownRequestPolicy(p: unknown, known: readonly string[]): p is string {\n  return typeof p === 'string' && known.includes(p);\n}","tryCatchPattern":"try {\n  await cluster.executeCommand(...);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unknown request policy')) {\n    // fix command metadata to use a supported policy\n  } else throw e;\n}","preventionTips":["Use only registered request policies for custom command metadata.","Keep node-redis version current with the command metadata you depend on.","Do not hand-craft policy strings; import them from the library constants."],"tags":["cluster","routing","command-policy","configuration"],"backgroundTag":null,"analyzedSha":"90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58","analyzedAt":"2026-08-11T15:37:21.243Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}