JuliusBrussee/caveman · critical · Error

agent-native setup failed

Error message

agent-native setup failed: ${(error as Error).message}${rollbackErrors.length ? `; rollback incomplete: ${rollbackErrors.join("; ")}` : "; changes rolled back"}

What it means

Thrown when agent-native setup fails partway through; the CLI rolls back each completed step (cloud MCP restore, disabling the native agent, journal cleanup) and throws this aggregate error. If any rollback step itself failed, all rollback errors are appended after "rollback incomplete:"; otherwise it ends with "; changes rolled back".

Solutions

  1. Fix the root cause named before the semicolon (permissions, disk space, agent state), then re-run `caveman setup --agent-native <agent>`.
  2. If the message says "rollback incomplete", address each appended rollback error — e.g. manually restore the previous cloud MCP entry or re-enable the native agent.
  3. Close running agent processes and disable file sync on the agent config directory before retrying.
  4. Use `caveman setup --agent-native <agent> --remove` to clear residual state, then set up fresh.

Example fix

// before: setup fails on read-only config dir, rollback partially fails too
agent-native setup failed: EACCES writing skills; rollback incomplete: EACCES restoring MCP
// after
$ chmod -R u+w ~/.claude
$ caveman setup --agent-native claude
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify preconditions before setup
accessSync(agentConfigDir, W_OK);
statfsSync(agentConfigDir); // ensure free space
if (nativeIntegrationStatus(agent).state === "installed") console.error("Already installed; remove first or re-run to refresh");

Try / catch

try {
  runAgentNativeSetup(agent);
} catch (err) {
  const msg = (err as Error).message;
  if (msg.includes("rollback incomplete")) {
    console.error(`Manual recovery needed: ${msg}`);
  } else {
    console.error(`Setup failed but was rolled back cleanly: ${msg}`);
  }
}

Prevention

When it happens

Trigger: Any failure inside the setup --agent-native try block (skill write failure, MCP registration failure, postflight failure) triggers the catch: rollbackCloudMcp/disableNativeAgent/unlink of the journal run, then this error is thrown with the original message plus rollback outcomes.

Common situations: Disk full or permission denied while writing skills; agent CLI changed config schema mid-setup; native agent install step failed; multiple rollback steps failing when the filesystem is in a bad state (read-only, sync conflicts).

Related errors

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

Appendix: source

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

      try {
        ensureAgentNativeIntegration(agentNative);
        installAgentNativeCloudMcp(agentNative, cloudMcp);
        cloudMcpApplied = true;
        installAgentNativeBundleSkills(agentNative, journal);
        verifyAgentNativeBundle(agentNative, journal, cloudMcp);
        atomicWriteFile(agentNativeBundleJournalPath(agentNative), Buffer.from(JSON.stringify(journal, null, 2) + "\n"));
        unlinkSync(agentNativeBundleJournalPath(agentNative, true));
      } catch (error) {
        const rollbackErrors: string[] = [];
        try { restoreAgentNativeBundleSkills(rollbackSkills); } catch (rollback) { rollbackErrors.push((rollback as Error).message); }
        if (cloudMcpApplied) {
          try { restoreAgentNativeCloudMcp(agentNative, rollbackCloudMcp); } catch (rollback) { rollbackErrors.push((rollback as Error).message); }
        }
        if (!nativeWasInstalled) {
          try { disableNativeAgent(agentNative); } catch (rollback) { rollbackErrors.push((rollback as Error).message); }
        }
        try { unlinkSync(agentNativeBundleJournalPath(agentNative, true)); } catch { /* original error remains authority */ }
        throw new Error(`agent-native setup failed: ${(error as Error).message}${rollbackErrors.length ? `; rollback incomplete: ${rollbackErrors.join("; ")}` : "; changes rolled back"}`);
      }
      const coreState = nativeCoreRuntimeState();
      const coreLabel = coreState.active ? "on" : coreState.configured ? "configured on; inactive under record mode/profile" : "off";
      console.error(`${mark("ok")} ${agentNative}: complete agent-native bundle ready`);
      console.error(dim(`→ coding policy: Core ${NATIVE_PACK.version} ${coreLabel}; change with \`caveman tools config set think.core ${coreState.configured ? "off" : "on"}\`; start new session to clear delivered context`));
      console.error(dim(`→ remove complete bundle: \`caveman setup --agent-native ${agentNative} --remove\``));
      console.error(dim("→ log in with `caveman login`; agent reads project context through existing CLI credentials"));
    });
  }
  if (install) return setupInstall(json);

  const rows = GO_BINARIES.map((b) => ({ ...b, resolved: resolveGoBin(b.name, b.env) }));
  const missingRequired = rows.filter((r) => r.required && !r.resolved);

  if (json) {
    print({
      binaries: rows.map((row) => ({
        name: row.name,

View on GitHub (pinned to 3ee70a1026)