paperclipai/paperclip · critical · Error

companyId is required because PAPERCLIP_COMPANY_ID is not se

Error message

companyId is required because PAPERCLIP_COMPANY_ID is not set

What it means

PaperclipMcpClient.resolveCompanyId returns the explicitly passed companyId if present, otherwise falls back to config.companyId (sourced from PAPERCLIP_COMPANY_ID). If both are empty after trim, it throws — every company-scoped tool needs a concrete company to act within.

Source

Thrown at packages/mcp-server/src/client.ts:65

    return text;
  }
}

export class PaperclipApiClient {
  constructor(private readonly config: PaperclipMcpConfig) {}

  get defaults() {
    return {
      companyId: this.config.companyId,
      agentId: this.config.agentId,
      runId: this.config.runId,
    };
  }

  resolveCompanyId(companyId?: string | null): string {
    const resolved = companyId?.trim() || this.config.companyId;
    if (!resolved) {
      throw new Error("companyId is required because PAPERCLIP_COMPANY_ID is not set");
    }
    return resolved;
  }

  resolveAgentId(agentId?: string | null): string {
    const resolved = agentId?.trim() || this.config.agentId;
    if (!resolved) {
      throw new Error("agentId is required because PAPERCLIP_AGENT_ID is not set");
    }
    return resolved;
  }

  async requestJson<T>(method: string, path: string, options: JsonRequestOptions = {}): Promise<T> {
    if (!path.startsWith("/")) {
      throw new Error(`API path must start with "/": ${path}`);
    }

    const url = new URL(path.slice(1), `${this.config.apiUrl}/`);

View on GitHub (pinned to 67001ec6eb)

Solutions

Set PAPERCLIP_COMPANY_ID in the server's environment and restart.
Pass companyId explicitly in the tool call arguments.
Verify the env var is actually visible to the process (print process.env at startup).

Example fix

// before: server started without PAPERCLIP_COMPANY_ID
// after
export PAPERCLIP_COMPANY_ID=comp_123
# restart MCP server

Defensive patterns

Strategy: validation

Validate before calling

const companyId = process.env.PAPERCLIP_COMPANY_ID?.trim();
if (!companyId) throw new Error('Startup config error: PAPERCLIP_COMPANY_ID must be set');

Prevention

Set PAPERCLIP_COMPANY_ID in the deployment env and verify it at startup.
Pass companyId explicitly on tool calls when running multi-company.
Print resolved config once at boot to catch stripped env vars early.

When it happens

Trigger: A tool is invoked without an explicit companyId argument while the server was started without PAPERCLIP_COMPANY_ID, or with that var set to whitespace only.

Common situations: Multi-tenant deployment where the operator expected per-call company selection but did not set the env fallback; .env not loaded in the MCP server process; value stripped by a secret manager.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/061ea49187a2f05d. Report an issue: GitHub.