{"record":{"id":"d50cdd801514f10f","repo":"JuliusBrussee/caveman","slug":"cannot-read-agent-agent-native-bundle-journal","errorCode":null,"errorMessage":"cannot read ${agent} agent-native bundle journal: ${(error as Error).message}","messagePattern":"cannot read (.+?) agent-native bundle journal: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2581,"sourceCode":"\nfunction agentNativeBundleJournalPath(agent: \"claude\" | \"codex\", pending = false): string {\n  return join(cavemanHome(), \"integrations\", `${agent}.agent-native-bundle${pending ? \".pending\" : \"\"}.json`);\n}\n\nfunction agentNativeBundleRemovalJournalPath(agent: \"claude\" | \"codex\"): string {\n  return join(cavemanHome(), \"integrations\", `${agent}.agent-native-bundle.removing.json`);\n}\n\nfunction readAgentNativeBundleJournal(agent: \"claude\" | \"codex\"): AgentNativeBundleJournal | null {\n  try {\n    const value = JSON.parse(readFileSync(agentNativeBundleJournalPath(agent), \"utf8\")) as AgentNativeBundleJournal;\n    if (value.schema_version !== 1 || value.agent !== agent || !value.cloud_mcp || !Array.isArray(value.skills)) {\n      throw new Error(\"unsupported bundle journal\");\n    }\n    return value;\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return null;\n    throw new Error(`cannot read ${agent} agent-native bundle journal: ${(error as Error).message}`);\n  }\n}\n\nfunction readPendingAgentNativeBundleJournal(agent: \"claude\" | \"codex\"): AgentNativeBundleJournal | null {\n  try {\n    const value = JSON.parse(readFileSync(agentNativeBundleJournalPath(agent, true), \"utf8\")) as AgentNativeBundleJournal;\n    if (value.schema_version !== 1 || value.agent !== agent || !value.cloud_mcp || !Array.isArray(value.skills)) {\n      throw new Error(\"unsupported pending bundle journal\");\n    }\n    return value;\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return null;\n    throw new Error(`cannot read pending ${agent} agent-native bundle journal: ${(error as Error).message}`);\n  }\n}\n\nfunction readPendingAgentNativeBundleRemoval(agent: \"claude\" | \"codex\"): AgentNativeBundleJournal | null {\n  try {","sourceCodeStart":2563,"sourceCodeEnd":2599,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L2563-L2599","documentation":"Reading the agent-native bundle journal (a JSON file recording which cloud MCP/skills were installed for 'claude' or 'codex') failed with an error other than ENOENT (missing file, which returns null). The installer wraps the underlying error message and rethrows so the user knows journal state is unreadable.","triggerScenarios":"readAgentNativeBundleJournal(agent) catches a non-ENOENT error from readFileSync/JSON.parse/schema validation of the journal file: EACCES/EISDIR on the journal path, invalid JSON, or schema_version !== 1 / wrong agent field / missing cloud_mcp or skills array.","commonSituations":"Journal file corrupted by a crash mid-write; file permissions changed after a user/UID switch; journal written by an older CLI with a different schema_version; journal path is a directory.","solutions":["Delete the corrupt journal file so the CLI can recreate it (it treats absence as null).","Check file permissions/ownership on the journal path (fix with chmod/chown).","Inspect the file to confirm valid JSON with schema_version 1 and correct 'agent' field.","Reinstall/upgrade the CLI so journal schema matches the current version."],"exampleFix":"// before\ncat ~/.caveman/claude-bundle.json  // corrupt JSON\n// after\nrm ~/.caveman/claude-bundle.json && caveman install  // recreates journal","handlingStrategy":"try-catch","validationCode":"const p = journalPath(agent);\ntry { JSON.parse(readFileSync(p, 'utf8')); } catch { console.warn(`journal ${p} corrupt — delete it before installing`); }","typeGuard":"function isJournal(v: unknown): v is AgentNativeBundleJournal {\n  return typeof v === 'object' && v !== null && (v as any).schema_version === 1 &&\n    typeof (v as any).agent === 'string' && Array.isArray((v as any).skills);\n}","tryCatchPattern":"try { await cavemanInstall() } catch (e) { if (String(e.message).includes('cannot read') && String(e.message).includes('journal')) { fs.rmSync(journalPath, { force: true }); await cavemanInstall(); } }","preventionTips":["Don't hand-edit journal files; let the CLI manage them.","Avoid killing the CLI mid-install, which can truncate journals.","Keep consistent user/UID so file permissions stay valid.","Upgrade the CLI and let it migrate journal schemas."],"tags":["json","journal","file-read","state"],"backgroundTag":"json-parse-error","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}