paperclipai/paperclip · error · Error

BROKER_TAILSCALE_BIN must be an absolute path

Error message

BROKER_TAILSCALE_BIN must be an absolute path

What it means

Path-shape guard in loadHostConfig for BROKER_TAILSCALE_BIN: the configured tailscale binary path is not absolute (does not start with '/'). Rejected because executing a relative path would resolve against the CWD, undermining the fixed privileged-execution model.

Source

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

  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("/")) {
    throw new Error("BROKER_TAILSCALE_BIN must be an absolute path");
  }
  const unsafe = registryPathUnsafeReason(config.registryPath);
  if (unsafe) {
    throw new Error(`refusing to start: ${unsafe} (${config.registryPath})`);
  }
  return config;
}

View on GitHub (pinned to 120ae5428f)

Solutions

1. Set BROKER_TAILSCALE_BIN to an absolute path, e.g. /usr/bin/tailscale.
2. Unset BROKER_TAILSCALE_BIN so the broker resolves tailscale from PATH.

When it happens

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