JuliusBrussee/caveman · error · Error

${findAgent(target)?.display_name ?? target} is unavailable;

Error message

${findAgent(target)?.display_name ?? target} is unavailable; repair host installation first

What it means

`caveman doctor <agent> --fix` computes availability via nativeHostProbe, which resolves the agent binary and runs `<bin> --version` with a 3s timeout; 'available' means launchable (binary found AND version probe exits 0). When the host is unavailable and there is no pending transaction to recover, --fix throws this error instead of trying to repair an integration whose host cannot run. The operator must fix the host installation first; doctor without --fix still prints a status report.

Source

Thrown at packages/cli/src/index.ts:8547

async function nativeDoctor(argv: string[]) {
  const fix = argv.includes("--fix");
  const target = argv.find((arg) => arg !== "--fix");
  if ((target !== "claude" && target !== "codex" && target !== "hermes" && target !== "gemini" && target !== "opencode" && target !== "pi" && target !== "aider" && target !== "generic") || argv.length !== (fix ? 2 : 1) || (fix && target === "generic")) commandUsage("doctor <claude|codex|hermes|gemini|opencode|pi|aider|generic> [--fix]");
  if (target === "generic") {
    const { host, port } = gatewayHostPort();
    const result = genericIntegrationStatus(await portListening(host, port));
    print({ ...result, repair: result.components.shared_runtime ? "caveman start" : "caveman setup --install", trust: "no host lifecycle hooks" });
    return;
  }
  const before = nativeIntegrationStatus(target);
  let fixResult: "not_needed" | "enabled" | "repaired" | "recovered" | undefined;
  if (fix) {
    if (!before.available && before.transaction_pending) {
      withIntegrationLock(target, () => recoverPendingNativeInstallUnlocked(target));
      fixResult = "recovered";
    } else if (!before.available) {
      throw new Error(`${findAgent(target)?.display_name ?? target} is unavailable; repair host installation first`);
    } else if (!before.installed) {
      enableNative([target]);
      fixResult = "enabled";
    } else if (before.state === "installed") {
      fixResult = "not_needed";
    } else {
      repairNativeAgent(target);
      fixResult = "repaired";
    }
  }
  const result = nativeIntegrationStatus(target);
  print({
    ...result,
    repair: result.installed ? `caveman doctor ${target} --fix` : `caveman enable ${target}`,
    trust: target === "codex" && result.installed ? "review through Codex /hooks" : "native host policy",
    ...(fixResult ? { fix: { attempted: true, result: fixResult } } : {}),
  });
  if (result.state === "degraded" || result.state === "unavailable") process.exitCode = 1;

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Verify the probe yourself: run `<agent-binary> --version` and make it exit 0 quickly (that is exactly what caveman executes)
2. Reinstall or repair the host agent (e.g. `npm install -g @anthropic-ai/claude-code`), remove hanging wrappers from PATH, then rerun `caveman doctor <agent> --fix`
3. If the binary exists but hangs, replace or fix the wrapper (no prompts, no network on --version); the probe times out at 3 seconds
4. If the host is intentionally absent, use `caveman disable <agent>` to remove the stale integration instead of --fix

Example fix

# before: host probe fails
caveman doctor claude --fix
# >> Claude Code is unavailable; repair host installation first
claude --version
# >> zsh: command not found: claude

# after: host repaired
npm install -g @anthropic-ai/claude-code && claude --version && caveman doctor claude --fix

// availability == binary found AND `<bin> --version` exits 0 within 3s
import { spawnSync } from 'node:child_process';
const probe = spawnSync(`${process.env.HOME}/.local/bin/claude`, ['--version'], { timeout: 3000, encoding: 'utf8' });
if (probe.error || probe.status !== 0) {
  console.error('host unavailable — fix the binary before `caveman doctor claude --fix`');
} else {
  console.log('host ok:', probe.stdout.trim());
}

catch (err) { if (err.message.includes('is unavailable; repair host installation first')) { /* fix/reinstall the host agent (make `<bin> --version` exit 0), then rerun with --fix */ } else throw err; }

When it happens

Trigger: `caveman doctor claude|codex|hermes|gemini|opencode|aider --fix` when the agent binary is missing, not executable, crashes on `--version`, or the version probe times out (slow disk, hung wrapper script, sandbox blocking spawn).

Common situations: Broken agent install (partial npm uninstall, corrupted binary); a wrapper script that prompts or hangs on `--version`; version-manager shims present but the underlying tool version removed; security software blocking child-process spawn.

Related errors

• caveman build: set CAVE_MODEL when zero or multiple provider
• caveman-code: neither rg nor grep is available
• caveman-code: host command shell is not available
• caveman agent: no supported provider credential found
• caveman agent: multiple provider credentials found; set CAVE

AI-assisted analysis of JuliusBrussee/caveman@5184b3d11a (2026-08-18). Data as JSON: /api/errors/9db9c337e70ac71c. Report an issue: GitHub.