JuliusBrussee/caveman · error · Error

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

Error message

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

What it means

With no explicit model requested, the agent infers the provider from which credential env vars are present (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY). Zero credentials means there is no model it can legally call, so resolution fails before any network attempt.

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 27d5a3981a)

Solutions

Export exactly one provider credential, e.g. `export ANTHROPIC_API_KEY=sk-ant-...`
If using Docker/k8s, verify the variable actually reaches the process: `docker exec <c> env | grep -c _API_KEY`
Alternatively set CAVE_MODEL with an explicit provider/model if your gateway handles auth another way

Example fix

# before
node agent.js  # no keys in env

# after
export ANTHROPIC_API_KEY="sk-ant-..."
node agent.js

Defensive patterns

Strategy: validation

Validate before calling

const CREDENTIAL_VARS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"] as const;
const present = CREDENTIAL_VARS.filter((v) => process.env[v] && process.env[v] !== "");
if (present.length === 0) {
  throw new Error(`no provider credential; export one of: ${CREDENTIAL_VARS.join(", ")}`);
}

Prevention

Fail fast at boot: assert at least one credential env var before creating a session
In containers, use env_file or explicit -e flags and verify with a startup env check
Never assume ambient shell env reaches the process — pass secrets explicitly

When it happens

Trigger: Starting a coding session with none of ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY set (or all set to empty strings), and no explicit model / CAVE_MODEL override.

Common situations: Env vars not passed into Docker (`docker run` without -e or env_file); secrets loaded asynchronously after startup; CI job that forgot the secret step; local .env file not sourced.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/fc06ccf5d9a68a5d. Report an issue: GitHub.