paperclipai/paperclip · error · Error

missing required env: ${key}

Error message

missing required env: ${key}

What it means

requireEnv guard used by loadHostConfig for mandatory broker env vars (e.g. BROKER_NODE_IDENTITY). The variable is unset or whitespace-only. Fails at startup so a missing identity cannot degrade broker behavior at runtime.

Source

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

  socketPath: string;
  registryPath: string;
  auditPath: string;
  tailscaleBinPath: string;
  nodeIdentity: string;
  serviceUid: number;
  serviceGid: number;
  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"),

View on GitHub (pinned to 120ae5428f)

Solutions

1. Set the named required environment variable before starting the broker.

When it happens

Trigger: Thrown at packages/tailscale-https-broker/src/config.ts:28 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/a8a5b46480353237. Report an issue: GitHub.