JuliusBrussee/caveman · error · Error

caveman agent: multiple provider credentials found; set…

Error message

caveman agent: multiple provider credentials found; set CAVE_MODEL once

What it means

The unpinned-model auto-detect requires exactly one provider credential so the provider choice is unambiguous. This error is thrown when more than one of ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY|GOOGLE_API_KEY is set: the runtime refuses to guess between them and asks for an explicit pin via CAVE_MODEL.

Solutions

Set CAVE_MODEL=provider/model once to make the choice explicit
Or pass definition.model or a model in .caveman/provider.json, which skips auto-detection entirely
Or unset all but one provider credential in that shell/session

Example fix

# before
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

# after
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export CAVE_MODEL=anthropic/claude-haiku-4-5

Defensive patterns

Strategy: validation

Validate before calling

const families = new Set(
  ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"]
    .filter((k) => process.env[k] !== undefined)
    .map((k) => k.split("_")[0].toLowerCase()),
);
if (families.size > 1 && process.env.CAVE_MODEL === undefined) {
  process.env.CAVE_MODEL = "anthropic/claude-haiku-4-5"; // choose explicitly
}

Prevention

Set CAVE_MODEL in any environment that legitimately holds multiple provider keys
Scope CI secret groups so jobs only receive the one provider they need
Document for teammates that adding a second key requires an explicit pin

When it happens

Trigger: A workstation with both Anthropic and OpenAI keys exported (or any two of the three provider families) runs an agent with no CAVE_MODEL, no definition.model, and no model in .caveman/provider.json, so configured.length becomes 2 or 3.

Common situations: Dotfiles that export keys for several AI CLIs; CI jobs inheriting a broad secret group; adding a new provider's key without removing the old one; GOOGLE_API_KEY and OPENAI_API_KEY both set on a dev machine.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/30bbab52d05db7fd. Report an issue: GitHub.

Appendix: source

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

  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 766dce6b13)