paperclipai/paperclip · critical · Error

agentId is required because PAPERCLIP_AGENT_ID is not set

Error message

agentId is required because PAPERCLIP_AGENT_ID is not set

What it means

resolveAgentId mirrors resolveCompanyId: prefers an explicitly passed agentId, falls back to config.agentId (from PAPERCLIP_AGENT_ID), and throws when neither resolves. Agent identity is required for activity logging and run attribution on every mutating call.

Source

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

    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}/`);
    const headers: Record<string, string> = {
      Authorization: `Bearer ${this.config.apiKey}`,
      Accept: "application/json",
    };
    if (options.body !== undefined) {
      headers["Content-Type"] = "application/json";
    }
    if ((options.includeRunId ?? isWriteMethod(method)) && this.config.runId) {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Set PAPERCLIP_AGENT_ID in the server's environment.
2. Pass agentId explicitly in each tool call.
3. Confirm the env var reaches the process.

Example fix

// before: no PAPERCLIP_AGENT_ID
// after
export PAPERCLIP_AGENT_ID=agent_abc
# restart

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

When it happens

Trigger: A tool is invoked without an agentId argument while the server was started without PAPERCLIP_AGENT_ID (or it was whitespace).

Common situations: Same as 448: .env not loaded, var stripped by a launcher, or a multi-agent deployment that intended to pass agentId per call but did not.

Related errors

• companyId is required because PAPERCLIP_COMPANY_ID is not se
• Missing PAPERCLIP_API_URL
• Missing PAPERCLIP_API_KEY
• Environment variable ${envName} is empty or not set.
• Environment variable ${opts.apiKeyEnv.trim()} is not set

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