paperclipai/paperclip · error · UsageError

PAPERCLIP_API_URL is required

Error message

PAPERCLIP_API_URL is required

What it means

Config validation in normalizeApiBaseUrl: the --api-url flag (or equivalent) is missing, empty, or whitespace-only, so the bridge cannot build its API base URL. Trailing slashes are trimmed and /api appended when valid; provide the Paperclip instance base URL to proceed.

Source

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

function readStringFlag(args, name) {
  const value = args[name];
  if (typeof value !== "string" || value.trim().length === 0) return null;
  return value;
}

function requireStringFlag(args, name) {
  const value = readStringFlag(args, name);
  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) {

View on GitHub (pinned to 120ae5428f)

Solutions

1. Set the PAPERCLIP_API_URL environment variable to your Paperclip instance URL before running the bridge.

When it happens

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