What causes "caveman agent: no supported provider credential found" in JuliusBrussee/caveman?

Export one supported key, e.g. `export ANTHROPIC_API_KEY=sk-ant-...`, in the shell/process that launches the agent.

caveman agent: no supported provider credential found

Error message

caveman agent: no supported provider credential found

What it means

When no model is pinned, the runtime builds a baseline list from provider credentials: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`/`GOOGLE_API_KEY`. It throws this error when the list is empty — no supported provider credential is present in the environment — so no default model can be selected.

Solutions

Export one supported key, e.g. `export ANTHROPIC_API_KEY=sk-ant-...`, in the shell/process that launches the agent.
Pin a model AND ensure its provider credential exists (`CAVE_MODEL=openai/gpt-5.4-mini` still needs `OPENAI_API_KEY` for the provider call).
Verify the key names exactly (`GEMINI_API_KEY` or `GOOGLE_API_KEY`, `OPENAI_API_KEY`).
In CI, add the secret to the job environment; locally check `printenv | grep API_KEY`.

Example fix

// before
pnpm --dir public/agent test   # no API keys in env
// after
export ANTHROPIC_API_KEY=sk-ant-...
pnpm --dir public/agent test

Defensive patterns

Strategy: validation

Validate before calling

const keys = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"];
const present = keys.filter((k) => !!process.env[k]);
if (present.length === 0 && !process.env.CAVE_MODEL) {
  throw new Error(`no provider credentials; set one of ${keys.join(", ")}`);
}

Type guard

null

Try / catch

try {
  await agent.run(task);
} catch (e) {
  if ((e as Error).message === "caveman agent: no supported provider credential found") {
    console.error("Export ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY before running");
  } else throw e;
}

Prevention

Source your .env file or inject CI secrets before launching agent runs in the same process.
Check `printenv | grep API_KEY` in the exact environment the runner uses.
Use exact key names: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY.

When it happens

Trigger: Running an agent without `definition.model`/`CAVE_MODEL`/valid `.caveman/provider.json` while none of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY` is exported in the environment the process sees.

Common situations: Forgetting to source `.env` before running; exporting keys in a different shell/user than the runner; CI secrets not injected; key names misspelled (`OPENAI_APIKEY`); credentials removed after a machine wipe.

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

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/6955bbe295fa60f5. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/runtime.ts:3256

  const requested = typeof definition.model === "string"
    ? definition.model
    : process.env.CAVE_MODEL ?? localProviderModel(rootDir);
  if (requested) {
    const slash = requested.indexOf("/");
    if (slash <= 0 || slash === requested.length - 1) {
      throw new Error("caveman agent: pinned model must use provider/model format");
    }
    const model = models.getModel(requested.slice(0, slash), requested.slice(slash + 1));
    if (!model) throw new Error(`caveman agent: unknown model ${JSON.stringify(requested)}`);
    return model;
  }

  const configured: Array<[string, string]> = [];
  if (process.env.ANTHROPIC_API_KEY) configured.push(["anthropic", "claude-haiku-4-5"]);
  if (process.env.OPENAI_API_KEY) configured.push(["openai", "gpt-5.4-mini"]);
  if (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY) configured.push(["google", "gemini-2.5-flash"]);
  if (configured.length !== 1) {
    throw new Error(
      configured.length === 0
        ? "caveman agent: no supported provider credential found"
        : "caveman agent: multiple provider credentials found; set CAVE_MODEL once",
    );
  }
  const [provider, id] = configured[0]!;
  const model = models.getModel(provider, id);
  if (!model) throw new Error(`caveman agent: baseline model unavailable: ${provider}/${id}`);
  return model;
}

function localProviderModel(rootDir: string): string | undefined {
  try {
    const parsed = JSON.parse(readFileSync(resolve(rootDir, ".caveman/provider.json"), "utf8")) as { model?: unknown };
    return typeof parsed.model === "string" ? parsed.model : undefined;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
    throw new Error("caveman agent: invalid .caveman/provider.json");

View on GitHub (pinned to 3ee70a1026)