JuliusBrussee/caveman · error · Error

cannot read ${agent} agent-native bundle journal: ${(error a

Error message

cannot read ${agent} agent-native bundle journal: ${(error as Error).message}

What it means

readAgentNativeBundleJournal() reads ~/.caveman-cloud/integrations/<agent>.agent-native-bundle.json — the journal describing the last committed agent-native bundle state (skills + caveman-cloud MCP). Any error other than ENOENT — invalid JSON, or a shape failing validation (schema_version !== 1, wrong agent, missing cloud_mcp/skills array) — is rethrown with this message. The journal is what makes later recovery non-destructive, so an unreadable one is fatal to further setup steps.

Source

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

function agentNativeBundleJournalPath(agent: "claude" | "codex", pending = false): string {
  return join(cavemanHome(), "integrations", `${agent}.agent-native-bundle${pending ? ".pending" : ""}.json`);
}

function agentNativeBundleRemovalJournalPath(agent: "claude" | "codex"): string {
  return join(cavemanHome(), "integrations", `${agent}.agent-native-bundle.removing.json`);
}

function readAgentNativeBundleJournal(agent: "claude" | "codex"): AgentNativeBundleJournal | null {
  try {
    const value = JSON.parse(readFileSync(agentNativeBundleJournalPath(agent), "utf8")) as AgentNativeBundleJournal;
    if (value.schema_version !== 1 || value.agent !== agent || !value.cloud_mcp || !Array.isArray(value.skills)) {
      throw new Error("unsupported bundle journal");
    }
    return value;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw new Error(`cannot read ${agent} agent-native bundle journal: ${(error as Error).message}`);
  }
}

function readPendingAgentNativeBundleJournal(agent: "claude" | "codex"): AgentNativeBundleJournal | null {
  try {
    const value = JSON.parse(readFileSync(agentNativeBundleJournalPath(agent, true), "utf8")) as AgentNativeBundleJournal;
    if (value.schema_version !== 1 || value.agent !== agent || !value.cloud_mcp || !Array.isArray(value.skills)) {
      throw new Error("unsupported pending bundle journal");
    }
    return value;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw new Error(`cannot read pending ${agent} agent-native bundle journal: ${(error as Error).message}`);
  }
}

function readPendingAgentNativeBundleRemoval(agent: "claude" | "codex"): AgentNativeBundleJournal | null {
  try {

View on GitHub (pinned to 27d5a3981a)

Solutions

  1. Inspect the journal file (~/.caveman-cloud/integrations/<agent>.agent-native-bundle.json) for truncation or unexpected fields
  2. Upgrade the caveman CLI to the version that wrote the journal if a schema skew is suspected
  3. If the bundle state is stale/unwanted, remove or rename the journal file after confirming no interrupted setup is pending, then re-run setup to rebuild it
Defensive patterns

Strategy: try-catch

Validate before calling

import { readFileSync } from "node:fs";
function journalReadable(p: string): boolean {
  try {
    const v = JSON.parse(readFileSync(p, "utf8"));
    return v.schema_version === 1 && Array.isArray(v.skills) && !!v.cloud_mcp;
  } catch { return false; }
}

Type guard

function isJournalReadError(e: unknown): boolean {
  return e instanceof Error && e.message.includes("cannot read ") && e.message.includes("agent-native bundle journal");
}

Try / catch

try {
  runCavemanAgentCommand("claude");
} catch (e) {
  if (isJournalReadError(e)) {
    // inspect/back up ~/.caveman-cloud/integrations/claude.agent-native-bundle.json, fix or remove, re-run
  } else throw e;
}

Prevention

When it happens

Trigger: Running `caveman <agent>` / setup / mcp flows when the journal file exists but is hand-edited, written by a different (older/newer) CLI version with another schema, truncated by a crash mid-write, or contains a mismatched agent id.

Common situations: Downgrading the CLI after a newer schema_version was written; a user or other tool editing files under ~/.caveman-cloud/integrations; disk-full or crash during an earlier setup leaving a partial journal.

Related errors

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