caveman-code: no supported provider credential found; set…

Error message

caveman-code: no supported provider credential found; set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY

What it means

When no explicit model is given, resolveCodingModelID builds candidates from provider credential env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY). If none are set, there is no model to default to, so the library throws telling you to set one of the supported credentials.

Solutions

Export ANTHROPIC_API_KEY (or OPENAI_API_KEY / GEMINI_API_KEY) in the environment
Set CAVE_MODEL plus the matching credential env var so the model resolves explicitly
Verify the key is exported in the same shell/process that runs caveman-code

Example fix

// before
$ cave run   # no credentials in env
// after
$ export ANTHROPIC_API_KEY=sk-ant-...
$ cave run

Defensive patterns

Strategy: fallback

Validate before calling

const hasCred = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"]
  .some((k) => !!process.env[k]);
if (!hasCred && !process.env.CAVE_MODEL) {
  throw new Error("Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY before running");
}

Type guard

null

Try / catch

try {
  await run(task);
} catch (err) {
  if ((err as Error).message.includes("no supported provider credential")) {
    console.error("Export a provider API key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY) and retry");
  } else throw err;
}

Prevention

Export one provider key in your shell profile and verify it in the same process
Check env vars exist in CI with a pre-flight step before running agents
Remember only Anthropic/OpenAI/Gemini credentials are auto-detected; others need explicit CAVE_MODEL

When it happens

Trigger: Calling caveman-code without a model argument/CAVE_MODEL while none of ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY is present in the environment.

Common situations: CI environments without exported secrets; running in a fresh shell where keys were set in another profile; using a provider (e.g. Bedrock, Azure) whose credential vars this library does not recognize.

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/fc06ccf5d9a68a5d. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/code.ts:562

}

function resolveCodingModelID(explicit: string | undefined): string {
  const requested = explicit ?? process.env.CAVE_MODEL;
  if (requested !== undefined && requested !== "") {
    const slash = requested.indexOf("/");
    if (slash <= 0 || slash === requested.length - 1) {
      throw new Error("caveman-code: model must use provider/model format");
    }
    return requested;
  }
  const configured: string[] = [];
  if (process.env.ANTHROPIC_API_KEY) configured.push("anthropic/claude-sonnet-4-6");
  if (process.env.OPENAI_API_KEY) configured.push("openai/gpt-5.5");
  if (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY) {
    configured.push("google/gemini-2.5-pro");
  }
  if (configured.length !== 1) {
    throw new Error(
      configured.length === 0
        ? "caveman-code: no supported provider credential found; set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY"
        : "caveman-code: multiple provider credentials found; set CAVE_MODEL to pick one",
    );
  }
  return configured[0]!;
}

// ---------------------------------------------------------------------------
// Session
// ---------------------------------------------------------------------------

export type SessionMode = "optimized" | "observe-only";

export interface CodingSessionOptions {
  conversation?: ConversationState;
  cave?: "auto" | "off";
  gatewayURL?: string;

View on GitHub (pinned to 3ee70a1026)