{"record":{"id":"40ef4bf3b6602d8d","repo":"paperclipai/paperclip","slug":"name-must-be-a-non-negative-integer-got-env","errorCode":null,"errorMessage":"${name} must be a non-negative integer, got: ${env[name]}","messagePattern":"(.+?) must be a non-negative integer, got: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/db/src/client.ts","lineNumber":192,"sourceCode":"  if (value === \"true\" || value === \"1\") return true;\n  if (value === \"false\" || value === \"0\") return false;\n  throw new Error(`${name} must be \"true\" or \"false\", got: ${env[name]}`);\n}\n\nfunction envPositiveInteger(env: NodeJS.ProcessEnv, name: string): number | undefined {\n  const value = env[name]?.trim();\n  if (value === undefined || value === \"\") return undefined;\n  if (!/^[1-9]\\d*$/.test(value)) {\n    throw new Error(`${name} must be a positive integer, got: ${env[name]}`);\n  }\n  return Number.parseInt(value, 10);\n}\n\nfunction envNonNegativeInteger(env: NodeJS.ProcessEnv, name: string): number | undefined {\n  const value = env[name]?.trim();\n  if (value === undefined || value === \"\") return undefined;\n  if (!/^(?:0|[1-9]\\d*)$/.test(value)) {\n    throw new Error(`${name} must be a non-negative integer, got: ${env[name]}`);\n  }\n  return Number.parseInt(value, 10);\n}\n\nfunction envNonEmptyString(env: NodeJS.ProcessEnv, name: string): string | undefined {\n  const value = env[name]?.trim();\n  if (value === undefined || value === \"\") return undefined;\n  return value;\n}\n\n/**\n * Database client tuning from the environment, so hosted deployments can\n * adapt to their connection topology (pooled endpoints, network latency)\n * without editing source. Every variable is optional. This function returns\n * only the values the environment sets; `resolveDatabaseClientOptions` adds\n * Paperclip's own defaults on top, and the driver defaults apply to the rest\n * — self-hosted setups need none of these.\n */","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/db/src/client.ts#L174-L210","documentation":"envNonNegativeInteger() parses a database client tuning env var (e.g. an idle timeout in seconds) and enforces a strict format: an unsigned non-negative integer with no signs, decimals, or whitespace-only garbage. Any other value throws, naming the env var and the raw value found, so bad environment configuration fails fast at client construction instead of producing silent misbehavior later.","triggerScenarios":"Setting an env var consumed by packages/db client (via the idleTimeoutSeconds path) to a non-integer or negative value: \"-5\", \"3.5\", \"1e3\", \"abc\", \"5s\", \"+10\", or a value with internal whitespace.","commonSituations":"Ops pasted a duration with a unit suffix (\"30s\", \"5m\") into an env var that expects bare seconds; YAML/Docker compose interpolated a value incorrectly leaving quotes or whitespace; someone set a negative value expecting it to mean 'disabled'; copy-paste introduced a comma (\"1,000\").","solutions":["Set the env var to a plain non-negative integer of seconds, e.g. \"30\" not \"30s\" or \"-1\".","To disable/leave the setting at its default, unset the variable entirely rather than setting it to 0-ish or negative placeholders (empty/undefined is accepted).","Check where the variable is defined (docker-compose, .env, k8s manifest) for stray units, quotes, or whitespace and fix it.","Validate the value with /^(?:0|[1-9]\\d*)$/ before deployment or in CI to catch bad configs early."],"exampleFix":"// before (docker-compose.yml)\nenvironment:\n  - DB_IDLE_TIMEOUT_SECONDS=30s\n// after\nenvironment:\n  - DB_IDLE_TIMEOUT_SECONDS=30","handlingStrategy":"validation","validationCode":"const raw = process.env.DB_IDLE_TIMEOUT_SECONDS;\nif (raw !== undefined && !/^(?:0|[1-9]\\d*)$/.test(raw.trim())) {\n  throw new Error(`DB_IDLE_TIMEOUT_SECONDS must be a non-negative integer of seconds, got: ${raw}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const client = createDbClient(process.env);\n} catch (err) {\n  if (err instanceof Error && /must be a non-negative integer/.test(err.message)) {\n    console.error(\"Bad DB tuning env var:\", err.message);\n    process.exit(1); // fail fast with a clear operator message\n  }\n  throw err;\n}","preventionTips":["Use bare integer seconds in DB tuning env vars — never \"30s\", \"5m\", negatives, or decimals.","Unset the variable to use defaults instead of setting placeholder or negative values.","Add an env-var lint/CI check that validates known numeric vars against the expected regex.","Watch for YAML/Docker quoting that leaks whitespace or unit suffixes into values."],"tags":["environment","configuration","validation","database"],"backgroundTag":"invalid-env-var-value","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}