{"record":{"id":"2951d51f37fed395","repo":"mastra-ai/mastra","slug":"server-draintimeout-must-be-a-finite-number-betwee","errorCode":null,"errorMessage":"server.drainTimeout must be a finite number between 0 and 2147483647 milliseconds","messagePattern":"server\\.drainTimeout must be a finite number between 0 and 2147483647 milliseconds","errorType":"validation","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"packages/deployer/src/server/index.ts","lineNumber":580,"sourceCode":"\n  // Attach injectWebSocket to app for backwards compatibility\n  // Consumers can use app directly, and optionally call app.injectWebSocket(server) for browser streaming\n  (app as any).injectWebSocket = browserStreamSetup?.injectWebSocket;\n\n  return app;\n}\n\nexport async function createNodeServer(mastra: Mastra, options: ServerBundleOptions = { tools: {} }) {\n  const app = await createHonoServer(mastra, options);\n  const injectWebSocket = (app as any).injectWebSocket;\n  const serverOptions = mastra.getServer();\n  const apiPrefix = serverOptions?.apiPrefix ?? '/api';\n  const drainTimeoutMs = serverOptions?.drainTimeout ?? 5000;\n  if (\n    serverOptions?.handleShutdownSignals !== false &&\n    (!Number.isFinite(drainTimeoutMs) || drainTimeoutMs < 0 || drainTimeoutMs > 2_147_483_647)\n  ) {\n    throw new RangeError('server.drainTimeout must be a finite number between 0 and 2147483647 milliseconds');\n  }\n\n  const key =\n    serverOptions?.https?.key ??\n    (process.env.MASTRA_HTTPS_KEY ? Buffer.from(process.env.MASTRA_HTTPS_KEY, 'base64') : undefined);\n  const cert =\n    serverOptions?.https?.cert ??\n    (process.env.MASTRA_HTTPS_CERT ? Buffer.from(process.env.MASTRA_HTTPS_CERT, 'base64') : undefined);\n  const isHttpsEnabled = Boolean(key && cert);\n\n  const bindHost = serverOptions?.host ?? process.env.MASTRA_HOST;\n  const host = bindHost ?? 'localhost';\n  const port = serverOptions?.port ?? (Number(process.env.PORT) || 4111);\n  const protocol = isHttpsEnabled ? 'https' : 'http';\n  const studioHost = serverOptions?.studioHost ?? host;\n  const studioProtocol = serverOptions?.studioProtocol ?? protocol;\n  const studioPort = serverOptions?.studioPort ?? port;\n","sourceCodeStart":562,"sourceCodeEnd":598,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/deployer/src/server/index.ts#L562-L598","documentation":"createNodeServer validates the optional serverOptions.drainTimeout before binding. Unless shutdown-signal handling is disabled (handleShutdownSignals === false), the value must be a finite number between 0 and 2147483647 ms (the max for Node setTimeout); otherwise a RangeError is thrown. The default is 5000 ms.","triggerScenarios":"Passing serverOptions.drainTimeout as NaN, Infinity, a negative number, a value > 2147483647, or a non-number (e.g. a string parsed from config) when creating the node server with shutdown signal handling enabled.","commonSituations":"Reading drainTimeout from env/config as a string ('5000') or from JSON as null; arithmetic producing NaN; setting an absurdly large value believing the unit is seconds instead of milliseconds.","solutions":["Set drainTimeout to a finite number of milliseconds within 0..2147483647 (e.g. 5000).","If loading from env, coerce explicitly: Number(process.env.DRAIN_TIMEOUT) and validate Number.isFinite before passing.","Set handleShutdownSignals: false only if you manage graceful shutdown yourself, which skips this validation."],"exampleFix":"// before\n{ drainTimeout: '30s' }\n// after\n{ drainTimeout: 30000 }","handlingStrategy":"validation","validationCode":"function parseDrainTimeout(raw) {\n  const n = typeof raw === 'number' ? raw : Number(raw);\n  if (!Number.isFinite(n) || n < 0 || n > 2_147_483_647) throw new RangeError(`drainTimeout must be 0..2147483647 ms, got ${raw}`);\n  return n;\n}\nconst drainTimeout = parseDrainTimeout(process.env.DRAIN_TIMEOUT ?? 5000);","typeGuard":"function isValidDrainTimeout(v: unknown): v is number {\n  return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 2_147_483_647;\n}","tryCatchPattern":"try {\n  const server = await createNodeServer(mastra, { drainTimeout });\n} catch (e) {\n  if (e instanceof RangeError && /drainTimeout/.test(e.message)) {\n    console.error('Fix server.drainTimeout: finite milliseconds in [0, 2147483647].');\n  }\n  throw e;\n}","preventionTips":["Coerce and validate numeric config from env/JSON before passing it to server options","Remember the unit is milliseconds (5000 = 5s)","Only set handleShutdownSignals: false if you own graceful shutdown"],"tags":["server","configuration","validation","shutdown"],"backgroundTag":"invalid-configuration-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}