paperclipai/paperclip · error

Environment variable

Error message

Environment variable ${opts.apiKeyEnv.trim()} is not set

What it means

readApiKeyEnvOption looked up the env var named by --api-key-env and found it unset or empty, so no API key can be sourced from it.

Solutions

1. Export the named environment variable with the API key before running, or pass the key directly.

When it happens

Trigger: Thrown at cli/src/commands/client/prompt.ts:274 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/b9c64c4543a55a0d. Report an issue: GitHub.

Appendix: source

Thrown at cli/src/commands/client/prompt.ts:274

  if (!matches) {
    throw new Error(
      `Agent key belongs to ${agent.name} (${agent.id}), not '${reference}'. Use the matching agent or a board prompt.`,
    );
  }
}

function agentSummary(agent: Agent): PromptResult["agent"] {
  return {
    id: agent.id,
    name: agent.name,
    urlKey: typeof agent.urlKey === "string" ? agent.urlKey : null,
  };
}

function readApiKeyEnvOption(opts: PromptOptions): string | undefined {
  if (!opts.apiKeyEnv?.trim()) return undefined;
  const value = process.env[opts.apiKeyEnv.trim()]?.trim();
  if (!value) throw new Error(`Environment variable ${opts.apiKeyEnv.trim()} is not set`);
  return value;
}

View on GitHub (pinned to 120ae5428f)