paperclipai/paperclip · error

${name} must be a non-negative integer, got: ${env[name]}

Error message

${name} must be a non-negative integer, got: ${env[name]}

What it means

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.

Source

Thrown at packages/db/src/client.ts:192

  if (value === "true" || value === "1") return true;
  if (value === "false" || value === "0") return false;
  throw new Error(`${name} must be "true" or "false", got: ${env[name]}`);
}

function envPositiveInteger(env: NodeJS.ProcessEnv, name: string): number | undefined {
  const value = env[name]?.trim();
  if (value === undefined || value === "") return undefined;
  if (!/^[1-9]\d*$/.test(value)) {
    throw new Error(`${name} must be a positive integer, got: ${env[name]}`);
  }
  return Number.parseInt(value, 10);
}

function envNonNegativeInteger(env: NodeJS.ProcessEnv, name: string): number | undefined {
  const value = env[name]?.trim();
  if (value === undefined || value === "") return undefined;
  if (!/^(?:0|[1-9]\d*)$/.test(value)) {
    throw new Error(`${name} must be a non-negative integer, got: ${env[name]}`);
  }
  return Number.parseInt(value, 10);
}

function envNonEmptyString(env: NodeJS.ProcessEnv, name: string): string | undefined {
  const value = env[name]?.trim();
  if (value === undefined || value === "") return undefined;
  return value;
}

/**
 * Database client tuning from the environment, so hosted deployments can
 * adapt to their connection topology (pooled endpoints, network latency)
 * without editing source. Every variable is optional. This function returns
 * only the values the environment sets; `resolveDatabaseClientOptions` adds
 * Paperclip's own defaults on top, and the driver defaults apply to the rest
 * — self-hosted setups need none of these.
 */

View on GitHub (pinned to 01ad858492)

Solutions

1. Set the env var to a plain non-negative integer of seconds, e.g. "30" not "30s" or "-1".
2. 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).
3. Check where the variable is defined (docker-compose, .env, k8s manifest) for stray units, quotes, or whitespace and fix it.
4. Validate the value with /^(?:0|[1-9]\d*)$/ before deployment or in CI to catch bad configs early.

Example fix

// before (docker-compose.yml)
environment:
  - DB_IDLE_TIMEOUT_SECONDS=30s
// after
environment:
  - DB_IDLE_TIMEOUT_SECONDS=30

const raw = process.env.DB_IDLE_TIMEOUT_SECONDS;
if (raw !== undefined && !/^(?:0|[1-9]\d*)$/.test(raw.trim())) {
  throw new Error(`DB_IDLE_TIMEOUT_SECONDS must be a non-negative integer of seconds, got: ${raw}`);
}

try {
  const client = createDbClient(process.env);
} catch (err) {
  if (err instanceof Error && /must be a non-negative integer/.test(err.message)) {
    console.error("Bad DB tuning env var:", err.message);
    process.exit(1); // fail fast with a clear operator message
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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").

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• Seed validation found an incomplete auth, membership, compan
• ${label} must be an integer between 1 and ${maximum}.
• PAPERCLIP_EVAL_MAX_CAMPAIGN_COST_USD must be a positive fini
• Runner live rotation requires a valid generated-at time
• --agent-name cannot be empty.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/40ef4bf3b6602d8d. Report an issue: GitHub.