paperclipai/paperclip · error · Error

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

Error message

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

What it means

`readApiKeyEnvOption` reads the env var named by `--api-key-env`. If the option is set (non-empty) but `process.env[<name>]` is empty/whitespace, it throws naming the variable. This lets the agent-prompt command pull the agent API key from a named env var instead of `--api-key`.

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 67001ec6eb)

Solutions

1. Export the named variable in the running shell: `export FOO=<agent-key>` (or source the `.env`)
2. Check the spelling/case of the variable passed to `--api-key-env`
3. In CI, confirm the secret is mapped into the step's environment under that exact name

Example fix

# before
paperclipai agent prompt --api-key-env AGENT_TOKEN "do work"   # AGENT_TOKEN unset
# after
export AGENT_TOKEN=<agent-key>
paperclipai agent prompt --api-key-env AGENT_TOKEN "do work"

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

When it happens

Trigger: Running `paperclipai agent prompt --api-key-env FOO ...` when `FOO` is not exported or is set to whitespace in the current shell/process.

Common situations: Typo in the env var name; the var is set in a different shell/session or `.env` file that was not sourced; CI secret not injected into the runner env; the var name was renamed but the CLI flag was not updated.

Related errors

• Environment variable ${envName} is empty or not set.
• Environment variable ${opts.valueEnv} is empty or unset.
• Challenge secret is required. Pass --token or --token-env.
• Profile '${ctx.profileName}' is persona=${ctx.profile.person
• Agent authentication failed

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