JuliusBrussee/caveman · error

caveman-code: model must use provider/model format

Error message

caveman-code: model must use provider/model format

What it means

resolveCodingModelID requires an explicit model (or CAVE_MODEL env var) to be in 'provider/model' form, e.g. 'anthropic/claude-sonnet-4-6'. It throws when the value has no '/', starts with '/', or ends with '/'.

Solutions

  1. Set CAVE_MODEL to provider/model format, e.g. 'anthropic/claude-sonnet-4-6'
  2. Pass the explicit model option in provider/model format instead of relying on env
  3. Unset CAVE_MODEL to let the library auto-pick from available provider credentials

Example fix

// before
export CAVE_MODEL=claude-sonnet-4-6
// after
export CAVE_MODEL=anthropic/claude-sonnet-4-6
Defensive patterns

Strategy: validation

Validate before calling

const model = process.env.CAVE_MODEL;
if (model && !/^[^/]+\/[^/]+$/.test(model)) {
  throw new Error(`CAVE_MODEL must be provider/model, got: ${model}`);
}

Type guard

const isProviderModel = (m: string): boolean => {
  const i = m.indexOf("/");
  return i > 0 && i < m.length - 1;
};

Try / catch

try {
  await run({ model: process.env.CAVE_MODEL });
} catch (err) {
  if ((err as Error).message.includes("provider/model format")) {
    throw new Error(`Fix CAVE_MODEL (got "${process.env.CAVE_MODEL}"); e.g. anthropic/claude-sonnet-4-6`);
  } else throw err;
}

Prevention

When it happens

Trigger: Setting CAVE_MODEL to 'claude-sonnet-4-6' (missing provider prefix), '/openai/gpt-5.5' (leading slash), or 'openai/' (trailing slash); passing an explicit model argument in any of those malformed shapes.

Common situations: Copying a model name from a provider console without the provider prefix; CAVE_MODEL exported from shell config with a shorthand name; trailing slash typo from templated config strings.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

      exitCode = code;
      finish();
    });
    // `close` waits for stdio EOF, which a surviving background descendant never
    // gives. `exit` is the command's own answer, so the run settles on it with
    // whatever output arrived rather than waiting on a process it does not own.
    child.once("exit", (code) => {
      exitCode = code;
      setTimeout(finish, EXIT_FLUSH_GRACE_MS).unref();
    });
  });
}

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]!;
}

View on GitHub (pinned to 3ee70a1026)