JuliusBrussee/caveman · error · Error

caveman-cloud MCP registration failed exact postflight

Error message

${agent} caveman-cloud MCP registration failed exact postflight

What it means

Thrown by verifyAgentNativeBundle when the deeper exact-match check agentNativeCloudMcpMatches fails even though the basic marker comparison passed. It means the agent's recorded caveman-cloud MCP registration does not match the exact expected registration shape required by postflight.

Solutions

  1. Re-run `caveman setup --agent-native <agent>` so the exact registration is rewritten in the current agent config schema.
  2. Update (or pin) the agent CLI version: a schema change between versions is the most common cause of an exact-match failure.
  3. Inspect agentNativeCloudMcpMatches expectations and the agent's config to identify which field diverges, and remove the extra/stale fields.
  4. Remove the bundle with `caveman setup --agent-native <agent> --remove` and set it up fresh.

Example fix

// before: agent CLI auto-upgraded mid-setup, schema changed
$ claude update & caveman setup --agent-native claude
// after: pin/complete the agent version before setup
$ claude --version  # confirm stable version
$ caveman setup --agent-native claude
Defensive patterns

Strategy: validation

Validate before calling

if (!agentNativeCloudMcpMatches(agent, expectedCloudMcp)) {
  console.error("exact MCP registration mismatch; re-run caveman setup --agent-native " + agent);
}

Try / catch

try {
  verifyAgentNativeBundle(agent, journal, cloudMcp);
} catch (err) {
  if (/failed exact postflight/.test((err as Error).message)) {
    console.error("Agent config schema drifted; pin agent version and re-run setup");
  }
}

Prevention

When it happens

Trigger: Setup wrote the MCP entry but the agent's stored representation differs in fields beyond command/args (extra keys, changed env, different scope/file) — agentNativeCloudMcpMatches returns false after the simple marker comparison succeeded.

Common situations: Agent CLI version changed its MCP config schema between setup and verification; the agent merged the entry with extra fields; a config migration restructured where MCP servers are recorded.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

    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;
  }
  for (const skill of journal.skills) {
    const current = fileBytes(skill.file);
    if (!current || bytesHash(current) !== skill.after_sha256) throw new Error(`${skill.file} changed after setup; refusing destructive bundle removal`);

View on GitHub (pinned to 3ee70a1026)