JuliusBrussee/caveman · error

caveman agent: baseline model unavailable

Error message

caveman agent: baseline model unavailable: ${provider}/${id}

What it means

When credentials imply exactly one baseline provider/model, the runtime resolves it via `models.getModel(provider, id)` and throws `caveman agent: baseline model unavailable: <provider>/<id>` if that pair is not registered. This is a registry-vs-catalog mismatch: your credential is recognized but the runtime has no model entry for the default it would pick.

Solutions

  1. Pin an explicitly registered model with `CAVE_MODEL=<provider>/<model>` (e.g. `anthropic/claude-haiku-4-5`) to bypass baseline selection.
  2. Update the package/runtime so the registry contains the current baseline default.
  3. Check which models `models.getModel` supports in your installed version and set a key for a provider whose baseline resolves.

Example fix

// before
export OPENAI_API_KEY=...   # baseline openai/gpt-5.4-mini not in registry
// after
export OPENAI_API_KEY=...
export CAVE_MODEL=openai/gpt-5.4-mini  # or upgrade the runtime
Defensive patterns

Strategy: fallback

Validate before calling

null

Type guard

null

Try / catch

try {
  await agent.run(task);
} catch (e) {
  if ((e as Error).message.startsWith("caveman agent: baseline model unavailable")) {
    console.error("Pin CAVE_MODEL to a registered model or update the runtime package");
  } else throw e;
}

Prevention

When it happens

Trigger: Only one provider key is set (e.g. `OPENAI_API_KEY`) and `models.getModel("openai", "gpt-5.4-mini")` returns undefined — the runtime version predates or postdates that default id, or the model registry was trimmed.

Common situations: Version skew between the runtime package and its model registry; a fork/stub registry in tests; a runtime release where the baseline default id was renamed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

    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");
  }
}

/**
 * Point a model at the gateway when the gateway speaks its dialect.
 *
 * The three routes below are the only ones the Caveman gateway proxies. Every
 * other provider Pi can reach (xai, groq, bedrock, openrouter, …) keeps its own

View on GitHub (pinned to 3ee70a1026)