paperclipai/paperclip · error · UsageError

PAPERCLIP_BRIDGE_API_KEY is required

Error message

PAPERCLIP_BRIDGE_API_KEY is required

What it means

Credential validation in getConfig: neither PAPERCLIP_BRIDGE_API_KEY nor PAPERCLIP_API_KEY is set (after trim), so the bridge skill has no bearer credential to authenticate to the Paperclip API. Export one of the env vars in the skill's environment before running the bridge.

Source

Thrown at packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjs:107

  if (!value) throw new UsageError(`Missing required --${name}`);
  return value;
}

function boolFlag(args, name) {
  return args[name] === true;
}

function normalizeApiBaseUrl(raw) {
  if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
    throw new UsageError("PAPERCLIP_API_URL is required");
  }
  const trimmed = raw.trim().replace(/\/+$/, "");
  return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
}

function getConfig() {
  const apiKey = process.env.PAPERCLIP_BRIDGE_API_KEY?.trim() || process.env.PAPERCLIP_API_KEY?.trim();
  if (!apiKey) throw new UsageError("PAPERCLIP_BRIDGE_API_KEY is required");
  return {
    apiBaseUrl: normalizeApiBaseUrl(process.env.PAPERCLIP_API_URL),
    apiKey,
    runId: process.env.PAPERCLIP_RUN_ID?.trim() || null,
    companyId: process.env.PAPERCLIP_COMPANY_ID?.trim() || null,
    agentId: process.env.PAPERCLIP_AGENT_ID?.trim() || null,
  };
}

async function readBody(args, textFlag, fileFlag) {
  const direct = readStringFlag(args, textFlag);
  const file = readStringFlag(args, fileFlag);
  if (direct && file) throw new UsageError(`Use either --${textFlag} or --${fileFlag}, not both`);
  if (direct) return direct;
  if (!file) return null;
  if (file === "-") {
    return await new Promise((resolve, reject) => {
      let data = "";

View on GitHub (pinned to 120ae5428f)

Solutions

1. Set the PAPERCLIP_BRIDGE_API_KEY environment variable to a valid agent API key before running the bridge.

When it happens

Trigger: Thrown at packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjs:107 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/11142f4a69482b31. Report an issue: GitHub.