JuliusBrussee/caveman · error

${agent} caveman-cloud MCP postflight mismatch

Error message

${agent} caveman-cloud MCP postflight mismatch

What it means

Postflight check in verifyAgentNativeBundle: after setup, the agent's config must contain an MCP server marker named "caveman-cloud" whose command and args exactly equal the ones the installer applied (compared via string equality and JSON.stringify of args). A missing marker or any command/args difference throws.

Source

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

function installAgentNativeBundleSkills(agent: "claude" | "codex", journal: AgentNativeBundleJournal): void {
  const originals = new Map(journal.skills.map((skill) => [skill.file, skill.before_base64]));
  journal.skills = agentNativeSkillFiles(agent).map(({ file, body }) => {
    mkdirSync(dirname(file), { recursive: true });
    atomicWriteFile(file, Buffer.from(body));
    return {
      file,
      before_base64: originals.get(file) ?? null,
      after_sha256: bytesHash(Buffer.from(body)),
    };
  });
}

function verifyAgentNativeBundle(agent: "claude" | "codex", journal: AgentNativeBundleJournal, cloudMcp: { command: string; args: string[] }): void {
  const status = nativeIntegrationStatus(agent);
  if (status.state !== "installed") throw new Error(`${agent} native integration postflight is ${status.state}`);
  const marker = readMcpServerMarker(agent, "caveman-cloud");
  if (!marker || marker.command !== cloudMcp.command || JSON.stringify(marker.args) !== JSON.stringify(cloudMcp.args)) {
    throw new Error(`${agent} caveman-cloud MCP postflight mismatch`);
  }
  if (!agentNativeCloudMcpMatches(agent, cloudMcp)) {
    throw new Error(`${agent} caveman-cloud MCP registration failed exact postflight`);
  }
  for (const skill of journal.skills) {
    const current = fileBytes(skill.file);
    if (!current || bytesHash(current) !== skill.after_sha256) throw new Error(`${skill.file} failed skill postflight`);
  }
}

function removeAgentNativeBundle(agent: "claude" | "codex"): void {
  recoverPendingAgentNativeRemoval(agent);
  recoverPendingAgentNativeBundle(agent);
  const journal = readAgentNativeBundleJournal(agent);
  if (!journal) {
    process.stderr.write(`${mark("warn")} ${agent}: no agent-native bundle journal found\n`);
    return;
  }

View on GitHub (pinned to 27d5a3981a)

Solutions

  1. Close all running instances of the agent, then re-run `caveman setup --agent-native <agent>`
  2. Manually inspect the agent config's mcpServers."caveman-cloud" entry and correct command/args to match what setup printed
  3. Remove the bundle (`--remove`) and reinstall so the marker is written fresh
  4. Ensure no wrapper script rewrites the agent config on launch
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: confirm agent config can hold the marker and none exists yet
import { readFileSync } from "node:fs";
const cfg = JSON.parse(readFileSync("~/.claude.json".replace("~", process.env.HOME!), "utf8"));
if (cfg.mcpServers?.["caveman-cloud"]) {
  console.error("caveman-cloud already registered; remove the bundle first to avoid marker mismatch");
}

Type guard

function isMcpMarker(v: unknown): v is { command: string; args: string[] } {
  return !!v && typeof (v as any).command === "string" && Array.isArray((v as any).args)
    && (v as any).args.every((a: unknown) => typeof a === "string");
}

Try / catch

try {
  await setup(["--agent-native", agent]);
} catch (error) {
  if (/caveman-cloud MCP postflight mismatch/.test((error as Error).message)) {
    // close agent processes, then retry once; a running agent rewrites config
    await closeAgentSessions(agent);
    await setup(["--agent-native", agent]);
  } else throw error;
}

Prevention

When it happens

Trigger: Running `caveman setup --agent-native <agent>` where the caveman-cloud MCP entry was not persisted, was rewritten by the agent itself, or arg ordering/JSON key order differs after stringification. Also triggered if another tool overwrote the agent config between write and verification.

Common situations: The agent (claude/codex) rewrites its config file on exit and drops or reorders MCP entries; arg arrays serialized with different key order; concurrent agent session flushed config mid-setup; manual edits to the MCP block.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/374a422673bc0b08. Report an issue: GitHub.