JuliusBrussee/caveman · error

caveman agent: unknown model

Error message

caveman agent: unknown model ${JSON.stringify(requested)}

What it means

After the `provider/model` format check, the runtime looks the model up via `models.getModel(provider, id)` and throws `caveman agent: unknown model <json>` when no registered model matches the pinned identifier. The pin came from `definition.model`, `CAVE_MODEL`, or `.caveman/provider.json`, and the provider/model pair is not in the model registry.

Solutions

  1. Correct the model id to a registered one, e.g. `openai/gpt-5.4-mini` or `anthropic/claude-haiku-4-5` (as listed in the runtime's baseline defaults).
  2. Run the package's `doctor` CLI to see which providers/models the runtime recognizes.
  3. Unset `CAVE_MODEL` (and fix `provider.json`) to let the runtime pick a baseline model from available credentials.
  4. Check for version drift: a model registered in a newer runtime may be unknown here — update the package.

Example fix

// before
CAVE_MODEL=anthropic/claude-3-haiku-20240307
// after
CAVE_MODEL=anthropic/claude-haiku-4-5
Defensive patterns

Strategy: validation

Validate before calling

import { getModel } from "@mariozechner/pi-ai";
const [provider, id] = (process.env.CAVE_MODEL ?? "").split("/");
if (process.env.CAVE_MODEL && !getModel(provider, id)) throw new Error(`unknown model: ${process.env.CAVE_MODEL}`);

Type guard

null

Try / catch

try {
  await agent.run(task);
} catch (e) {
  if ((e as Error).message.startsWith("caveman agent: unknown model")) {
    console.error("Fix CAVE_MODEL/provider.json to a registered model id");
  } else throw e;
}

Prevention

When it happens

Trigger: `CAVE_MODEL=openai/gpt-9-turbo` (nonexistent id), a typo like `anthropic/claude-haiku-4.5` vs the registered id, or a provider slug the registry does not know (`gpt/4o`).

Common situations: Using a model name from provider marketing docs that differs from the registry id; upgrading the runtime where registry ids changed; hand-editing `provider.json` with an invented pair.

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

Appendix: source

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

  // future OAuth-capable Google provider cannot be relabeled as metered.
  if (provider === "google" && process.env.GOOGLE_API_KEY) return "metered";
  return "unknown";
}

function resolveModel(definition: AgentDefinition, models: Models, rootDir: string): Model<Api> {
  if (typeof definition.model === "object" && "provider" in definition.model) {
    return definition.model;
  }
  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;

View on GitHub (pinned to 3ee70a1026)