paperclipai/paperclip · error · Error

--api-key-env must name a valid environment variable.

Error message

--api-key-env must name a valid environment variable.

What it means

resolveTestDriveBootstrap validates the --api-key-env option. When explicitly provided, its trimmed value must be a valid environment variable name (a letter or underscore followed by letters, digits, or underscores). This error means the flag was given but its value is not a usable env var identifier.

Source

Thrown at cli/src/commands/test-drive.ts:257

  if (!companyName) throw new Error("--company-name cannot be empty.");
  if (!agentName) throw new Error("--agent-name cannot be empty.");

  const model = options.model;
  if (model !== undefined && (!model || model.trim() !== model)) {
    throw new Error("--model cannot be empty or have surrounding whitespace.");
  }
  if (
    harness === "opencode" &&
    (!model || !/^openrouter\/[^/\s]+(?:\/[^/\s]+)*$/.test(model))
  ) {
    throw new Error(
      "OpenCode test drives require --model openrouter/<model>, with no empty path segments.",
    );
  }

  const sourceEnvName = options.apiKeyEnv?.trim() || definition.credentialTarget;
  if (options.apiKeyEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sourceEnvName)) {
    throw new Error("--api-key-env must name a valid environment variable.");
  }
  const credential = options.apiKey ?? env[sourceEnvName];
  if (!credential || credential.trim().length === 0) {
    throw new Error(
      `No credential found. Set ${sourceEnvName}, pass --api-key-env <variable>, or pass --api-key <value>.`,
    );
  }

  return {
    ...definition,
    companyName,
    agentName,
    ...(model ? { model } : {}),
    credential,
    credentialSource: options.apiKey !== undefined ? "--api-key" : sourceEnvName,
  };
}

View on GitHub (pinned to 01ad858492)

Solutions

1. Rename the flag value to a valid identifier, e.g. --api-key-env OPENROUTER_API_KEY
2. If the shell variable is empty, set it before invoking the command
3. Omit --api-key-env entirely to fall back to the app definition's default credentialTarget

Example fix

// before
paperclip test-drive <app> --api-key-env MY-API-KEY
// after
paperclip test-drive <app> --api-key-env MY_API_KEY

if (apiKeyEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv.trim())) {
  throw new Error('--api-key-env must be a valid env var name');
}

function isValidEnvVarName(v: unknown): v is string {
  return typeof v === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(v);
}

When it happens

Trigger: Passing --api-key-env with a value containing digits at the start (e.g. '1PASSWORD_API_KEY'), hyphens ('MY-API-KEY'), spaces, or an empty/whitespace-only string.

Common situations: Typing the env var name with hyphens instead of underscores; quoting an empty value; shell variable expansion producing an empty string (`--api-key-env "$MY_VAR"` when MY_VAR is unset).

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• --model must be the qualified Managed Agents model ${CLAUDE_
• --api-key-secret-id must be a UUID
• --max-session-list-cost-usd must resolve to at least one cen
• unknown argument: ${args[index] ?? ""}
• PAPERCLIP_EVAL_MAX_CAMPAIGN_COST_USD must be a positive fini

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/2de19d05107c0527. Report an issue: GitHub.