JuliusBrussee/caveman · critical · Error

agent-native bundle removal failed

Error message

agent-native bundle removal failed: ${(error as Error).message}; rollback incomplete: ${(rollback as Error).message}

What it means

Thrown when removing the agent-native bundle failed AND the attempt to restore the installed bundle from the journal also failed. The message chains the original removal error with the rollback error, telling the user the system is now in a partially removed state that automatic recovery could not fix.

Solutions

  1. Close running claude/codex processes and stop file-sync tools, then retry `caveman setup --agent-native <agent> --remove`.
  2. Read both error halves: fix the rollback error first (usually permissions or a missing journaled file), then retry removal.
  3. Manually restore from the removal journal: re-create/re-list files per journal and delete agentNativeBundleRemovalJournalPath so the pending-removal recovery can run cleanly next time.
  4. If unrecoverable, run setup again to rebuild a consistent bundle, then remove it cleanly.

Example fix

// before: remove with agent running
$ claude serve & caveman setup --agent-native claude --remove
Error: ... removal failed: EBUSY; rollback incomplete: EBUSY
// after
$ pkill -f claude
$ caveman setup --agent-native claude --remove
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check writability of every journaled path before attempting removal
const allWritable = [journal.skills.map(s => s.file), journal.removes ?? []].flat()
  .every(p => { try { accessSync(dirname(p), W_OK); return true; } catch { return false; } });
if (!allWritable) console.error("Fix permissions before removing the bundle");

Try / catch

try {
  removeAgentNativeBundle(agent);
} catch (err) {
  if (/rollback incomplete/.test((err as Error).message)) {
    console.error("Manual recovery required; close agents/sync tools, fix permissions, then re-run --remove");
  }
}

Prevention

When it happens

Trigger: During `--remove`, an error occurs while tearing down the bundle, the catch block calls restoreInstalledAgentNativeBundle, and that restoration itself throws (e.g. missing journaled files, permission errors) — the rollback catch then throws this combined error.

Common situations: Skill/MCP files locked by a running agent or file-sync tool; permissions changed since setup; journal references files that no longer exist so restore cannot recreate them; disk full during restore.

Related errors

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

Appendix: source

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

  if (journal.native_owned) {
    const nativeJournal = readNativeJournal(agent);
    if (nativeJournal) {
      for (const operation of nativeJournal.operations) restoreNativeOperation(operation);
    }
  }
  atomicWriteFile(agentNativeBundleRemovalJournalPath(agent), Buffer.from(JSON.stringify(journal, null, 2) + "\n"));
  try {
    restoreAgentNativeBundleSkills(journal.skills);
    restoreAgentNativeCloudMcp(agent, journal.previous_cloud_mcp);
    if (journal.native_owned) disableNativeAgent(agent);
    unlinkSync(agentNativeBundleJournalPath(agent));
    unlinkSync(agentNativeBundleRemovalJournalPath(agent));
  } catch (error) {
    try {
      restoreInstalledAgentNativeBundle(agent, journal);
      unlinkSync(agentNativeBundleRemovalJournalPath(agent));
    } catch (rollback) {
      throw new Error(`agent-native bundle removal failed: ${(error as Error).message}; rollback incomplete: ${(rollback as Error).message}`);
    }
    throw new Error(`agent-native bundle removal failed: ${(error as Error).message}; installed bundle restored`);
  }
  process.stderr.write(`${mark("ok")} ${agent}: agent-native bundle removed; prior skills and cloud MCP restored\n`);
}

async function setup(argv: string[] = []) {
  const json = argv.includes("--json");
  const install = argv.includes("--install");
  const removeBundle = argv.includes("--remove");
  const agentNative = flagFrom(argv, "--agent-native", "");
  const hasAgentNativeFlag = argv.includes("--agent-native") || argv.some((arg) => arg.startsWith("--agent-native="));
  const unknown = argv.filter((arg, index) =>
    arg !== "--json"
    && arg !== "--install"
    && arg !== "--remove"
    && arg !== "--agent-native"
    && !arg.startsWith("--agent-native=")

View on GitHub (pinned to 3ee70a1026)