{"record":{"id":"518bed55072b402a","repo":"paperclipai/paperclip","slug":"missing-paperclip-api-url","errorCode":null,"errorMessage":"Missing PAPERCLIP_API_URL","messagePattern":"Missing PAPERCLIP_API_URL","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/mcp-server/src/config.ts","lineNumber":25,"sourceCode":"}\n\nfunction nonEmpty(value: string | undefined): string | null {\n  return typeof value === \"string\" && value.trim().length > 0 ? value.trim() : null;\n}\n\nfunction stripTrailingSlash(value: string): string {\n  return value.replace(/\\/+$/, \"\");\n}\n\nexport function normalizeApiUrl(apiUrl: string): string {\n  const trimmed = stripTrailingSlash(apiUrl.trim());\n  return trimmed.endsWith(\"/api\") ? trimmed : `${trimmed}/api`;\n}\n\nexport function readConfigFromEnv(env: NodeJS.ProcessEnv = process.env): PaperclipMcpConfig {\n  const apiUrl = nonEmpty(env.PAPERCLIP_API_URL);\n  if (!apiUrl) {\n    throw new Error(\"Missing PAPERCLIP_API_URL\");\n  }\n  const apiKey = nonEmpty(env.PAPERCLIP_API_KEY);\n  if (!apiKey) {\n    throw new Error(\"Missing PAPERCLIP_API_KEY\");\n  }\n\n  return {\n    apiUrl: normalizeApiUrl(apiUrl),\n    apiKey,\n    companyId: nonEmpty(env.PAPERCLIP_COMPANY_ID),\n    agentId: nonEmpty(env.PAPERCLIP_AGENT_ID),\n    runId: nonEmpty(env.PAPERCLIP_RUN_ID),\n  };\n}\n","sourceCodeStart":7,"sourceCodeEnd":40,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/mcp-server/src/config.ts#L7-L40","documentation":"readConfigFromEnv requires PAPERCLIP_API_URL to be a non-empty string (via nonEmpty). Missing, empty, or whitespace-only values throw before any other config is read, so this is the first failure you hit when the MCP server cannot locate the Paperclip API.","triggerScenarios":"Starting the paperclip MCP server with PAPERCLIP_API_URL unset, empty, or whitespace; a launcher/docker entrypoint that does not export it.","commonSituations":"Forgot to copy .env into the runtime; docker-compose missing the env entry; CI secret not injected.","solutions":["Set PAPERCLIP_API_URL to the Paperclip API base (e.g. https://paperclip.example.com/api or the bare host — normalizeApiUrl appends /api).","Confirm the var is exported into the shell/process that starts the MCP server.","Check for trailing quotes or spaces in the value."],"exampleFix":"# before\n$ paperclip-mcp  # no env\n# after\nexport PAPERCLIP_API_URL=https://paperclip.example.com/api\nexport PAPERCLIP_API_KEY=sk_...\npaperclip-mcp","handlingStrategy":"validation","validationCode":"if (!process.env.PAPERCLIP_API_URL?.trim()) throw new Error('PAPERCLIP_API_URL must be set before starting the MCP server');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add a startup self-check that fails fast on missing env with a clear message.","Keep required Paperclip env vars in a single sourced .env or secret mount.","Validate the URL is reachable from the server host."],"tags":["configuration","env","startup-validation","paperclip-mcp"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}