paperclipai/paperclip · error · Error

No credential found. Set ${sourceEnvName}, pass --api-key-en

Error message

No credential found. Set ${sourceEnvName}, pass --api-key-env <variable>, or pass --api-key <value>.

What it means

After resolving the credential source environment variable (either --api-key-env or the app definition's credentialTarget), resolveTestDriveBootstrap checks that a non-empty credential is available. This error means no API key value could be found in the environment or on the command line for the test drive.

Source

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

  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,
  };
}

function worktreeExecutionArmed(
  settings: InstanceExperimentalSettings,
  instanceId: string,
): boolean {

View on GitHub (pinned to 01ad858492)

Solutions

1. Export the expected variable, e.g. export OPENROUTER_API_KEY=<your-key>
2. Pass the key inline with --api-key <value> (avoid in shared shells/logs)
3. Point at a set variable with --api-key-env <VAR_NAME>
4. Check `echo $<sourceEnvName>` to confirm the variable is set and non-empty in the same shell

Example fix

// before
paperclip test-drive someapp   # OPENROUTER_API_KEY unset
// after
export OPENROUTER_API_KEY=sk-or-...
paperclip test-drive someapp

const envName = apiKeyEnv?.trim() ?? 'OPENROUTER_API_KEY';
if (!process.env[envName]?.trim() && !apiKey) {
  throw new Error(`Set ${envName} or pass --api-key before running test-drive`);
}

function hasCredential(name: string): boolean {
  return typeof process.env[name] === 'string' && process.env[name]!.trim().length > 0;
}

try {
  await runTestDrive(opts);
} catch (e) {
  if (String(e.message).startsWith('No credential found')) {
    console.error(`Export ${envName} or pass --api-key`);
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Running test-drive when the resolved env var (e.g. the app's credentialTarget like OPENROUTER_API_KEY) is unset or empty, and neither --api-key-env pointing to a set variable nor --api-key <value> was supplied.

Common situations: Fresh machine or CI runner where the credential env var was never exported; variable exported in one shell but not the subshell running the CLI; typo'd variable name so env[sourceEnvName] is undefined.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• --api-key-env must name a valid environment variable.
• Managed installs require Node.js ${MINIMUM_NODE_VERSION} or
• Import cancelled.
• Could not open your browser automatically. Open this URL man
• Unknown config key ${warning.path}; did you mean ${warning.s

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