{"record":{"id":"9a3da0410a3d87c9","repo":"redis/node-redis","slug":"topologyrefreshonreconnectionattempt-must-be-undef","errorCode":null,"errorMessage":"topologyRefreshOnReconnectionAttempt must be undefined, false, a non-negative integer, or a function","messagePattern":"topologyRefreshOnReconnectionAttempt must be undefined, false, a non-negative integer, or a function","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/client/lib/cluster/cluster-reconnection-tracker.ts","lineNumber":45,"sourceCode":"  /**\n   * Validates that a strategy value is acceptable before use.\n   * @throws If the strategy is not supported\n   */\n  #validate(strategy?: ClusterTopologyRefreshOnReconnectionAttemptStrategy) {\n    if (\n      strategy === undefined ||\n      strategy === false ||\n      typeof strategy === 'function' ||\n      (\n        typeof strategy === 'number' &&\n        Number.isInteger(strategy) &&\n        strategy >= 0\n      )\n    ) {\n      return;\n    }\n\n    throw new TypeError('topologyRefreshOnReconnectionAttempt must be undefined, false, a non-negative integer, or a function');\n  }\n\n  constructor(strategy?: ClusterTopologyRefreshOnReconnectionAttemptStrategy) {\n    this.#validate(strategy);\n    this.#strategy = strategy;\n  }\n\n  get reconnectingAddresses() {\n    return new Set(this.#reconnectingClients.values());\n  }\n\n  get firstReconnectionAt() {\n    return this.#firstReconnectionAt;\n  }\n\n  /**\n   * Records a reconnection attempt for the given client and evaluates whether\n   * the configured delay has elapsed since the first attempt in this cycle.","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/redis/node-redis/blob/90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58/packages/client/lib/cluster/cluster-reconnection-tracker.ts#L27-L63","documentation":"Thrown by ClusterReconnectionTracker constructor validation when the topologyRefreshOnReconnectionAttemptStrategy option is not one of: undefined, false, a non-negative integer, or a function. The strategy controls when a cluster topology refresh is triggered after a node starts reconnecting; an invalid type is rejected at client construction time.","triggerScenarios":"Passing cluster option topologyRefreshOnReconnectionAttemptStrategy as a string ('5000'), a negative number (-1), a float (5.5), or an object. Passing it as a boolean true (only false is accepted).","commonSituations":"Reading the delay from an environment variable as a string and passing it uncoerced; passing a float milliseconds value; copy-paste from docs that showed a function but leaving stray characters; passing true expecting it to mean 'enabled'.","solutions":["Pass undefined (default 5s), false or 0 (disabled), a non-negative integer (ms delay), or a function.","If reading from env/config, coerce with Number() and validate Number.isInteger(v) && v >= 0 before passing.","Pass a function (firstReconnectionAt) => delay for custom logic instead of a value.","Do not pass true; use undefined for the default-enabled behavior."],"exampleFix":"// before\nconst cluster = createCluster({ rootNodes, topologyRefreshOnReconnectionAttemptStrategy: '5000' });\n// TypeError at construction\n\n// after\nconst cluster = createCluster({ rootNodes, topologyRefreshOnReconnectionAttemptStrategy: 5000 });","handlingStrategy":"validation","validationCode":"function validateTopologyStrategy(v: unknown): void {\n  if (v === undefined || v === false || typeof v === 'function' ||\n      (typeof v === 'number' && Number.isInteger(v) && v >= 0)) return;\n  throw new TypeError('Invalid topologyRefreshOnReconnectionAttemptStrategy');\n}\nvalidateTopologyStrategy(configValue);","typeGuard":"function isTopologyStrategy(v: unknown): v is undefined | false | number | ((t: number) => false | undefined | number) {\n  return v === undefined || v === false || typeof v === 'function' ||\n    (typeof v === 'number' && Number.isInteger(v) && v >= 0);\n}","tryCatchPattern":null,"preventionTips":["Pass undefined, false, a non-negative integer, or a function only.","Coerce env-string values with Number() and validate integer >= 0 before passing.","Do not pass true; use undefined for default behavior."],"tags":["cluster","configuration","validation","reconnect"],"backgroundTag":null,"analyzedSha":"90fd0652bc3f2a0a1b2f79fa9096b02a86b0ac58","analyzedAt":"2026-08-11T15:37:21.243Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}