paperclipai/paperclip · error · Error

${key} must be a non-negative integer

Error message

${key} must be a non-negative integer

What it means

requireUid guard in loadHostConfig: a UID/GID env var (BROKER_SERVICE_UID, BROKER_SERVICE_GID, BROKER_RUNTIME_UID) contains characters other than digits, i.e. not a canonical non-negative integer. Startup aborts because privilege-separating IDs must be exact.

Source

Thrown at packages/tailscale-https-broker/src/config.ts:35

  runtimeUid: number;
  /**
   * Operator-declared ports the broker must never mutate, parsed from
   * `BROKER_PROTECTED_PORTS` (PAP-17285). Empty when unset.
   */
  protectedPorts: number[];
}

function requireEnv(env: NodeJS.ProcessEnv, key: string): string {
  const value = env[key];
  if (!value || value.trim().length === 0) {
    throw new Error(`missing required env: ${key}`);
  }
  return value;
}

function requireUid(env: NodeJS.ProcessEnv, key: string): number {
  const raw = requireEnv(env, key);
  if (!/^[0-9]+$/.test(raw)) throw new Error(`${key} must be a non-negative integer`);
  return Number(raw);
}

export function loadHostConfig(env: NodeJS.ProcessEnv): BrokerHostConfig {
  const config: BrokerHostConfig = {
    socketPath: env.BROKER_SOCKET_PATH ?? "/run/paperclip-tailscale-broker/broker.sock",
    registryPath: env.BROKER_REGISTRY_PATH ?? "/var/lib/paperclip-tailscale-broker/registry.json",
    auditPath: env.BROKER_AUDIT_PATH ?? "/var/log/paperclip-tailscale-broker/audit.log",
    tailscaleBinPath: env.BROKER_TAILSCALE_BIN ?? "/usr/bin/tailscale",
    nodeIdentity: requireEnv(env, "BROKER_NODE_IDENTITY"),
    serviceUid: requireUid(env, "BROKER_SERVICE_UID"),
    serviceGid: requireUid(env, "BROKER_SERVICE_GID"),
    runtimeUid: requireUid(env, "BROKER_RUNTIME_UID"),
    // Throws on a malformed list so the broker refuses to start rather than
    // starting up silently protecting nothing (PAP-17285).
    protectedPorts: parseProtectedPorts(env.BROKER_PROTECTED_PORTS),
  };
  if (!config.tailscaleBinPath.startsWith("/")) {

View on GitHub (pinned to 120ae5428f)

Solutions

1. Set the named config key to a non-negative integer (0 or greater).
2. Remove the key from the environment/config to use the default value.

When it happens

Trigger: Thrown at packages/tailscale-https-broker/src/config.ts:35 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/a0ebb1d58ae3a5af. Report an issue: GitHub.