existing Codex Caveman block is corrupted; run `caveman doct

Error message

existing Codex Caveman block is corrupted; run `caveman doctor codex`

What it means

codexNativeConfig() strips previously stamped Caveman blocks from ~/.codex/config.toml (via stripCodexCavemanMcpToml/ProviderToml, then CODEX_NATIVE_ROOT/TABLES BEGIN/END pairs). For each marker pair it throws when BEGIN exists without END (or vice versa) — the managed TOML block was partially deleted or reordered and cannot be safely re-stamped.

Source

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

      kind: "aider-config",
      owned: { route, route_block: native.routeBlock, previous_route_line: native.previousRouteLine, read_block: native.readBlock, core_path: corePath },
    },
    {
      file: corePath,
      before: coreBefore,
      after: Buffer.from(core),
      kind: "aider-core",
      owned: { marker: AIDER_NATIVE_CORE_MARKER },
    },
  ];
}

function codexNativeConfig(source: string, gw: string, subscription: boolean, mcpBinary: string): { text: string; rootBlock: string; tablesBlock: string } {
  let stripped = stripCodexCavemanMcpToml(stripCodexCavemanProviderToml(source));
  for (const [begin, end] of [[CODEX_NATIVE_ROOT_BEGIN, CODEX_NATIVE_ROOT_END], [CODEX_NATIVE_TABLES_BEGIN, CODEX_NATIVE_TABLES_END]] as const) {
    const start = stripped.indexOf(begin);
    const finish = stripped.indexOf(end);
    if ((start === -1) !== (finish === -1)) throw new Error("existing Codex Caveman block is corrupted; run `caveman doctor codex`");
    if (start !== -1) stripped = `${stripped.slice(0, start)}${stripped.slice(finish + end.length)}`.trim();
  }
  const rootBlock = `${CODEX_NATIVE_ROOT_BEGIN}\nmodel_provider = "caveman"\n${CODEX_NATIVE_ROOT_END}`;
  const providerLines = codexCavemanProviderToml(gw, subscription).split("\n").slice(1).join("\n");
  const tablesBlock = [
    CODEX_NATIVE_TABLES_BEGIN,
    providerLines,
    "",
    "[mcp_servers.caveman]",
    `command = ${JSON.stringify(mcpBinary)}`,
    CODEX_NATIVE_TABLES_END,
  ].join("\n");
  const middle = stripped ? `\n\n${stripped}` : "";
  return { text: `${rootBlock}${middle}\n\n${tablesBlock}\n`, rootBlock, tablesBlock };
}

function codexNativeMutations(gw: string, mcpBinary: string): NativeMutation[] {
  const hooksPath = codexHooksPath();

View on GitHub (pinned to 27d5a3981a)

Solutions

Run `caveman doctor codex` to repair the corrupted block
Or hand-edit ~/.codex/config.toml: remove the orphaned marker line and any partial block content between it and the next section, leaving no Caveman markers
Re-run the codex native install

Example fix

# before — ~/.codex/config.toml
# <<< CAVEMAN NATIVE ROOT BEGIN <<<
model_provider = "caveman"
# (END marker missing)

# after — marker block fully removed (or `caveman doctor codex`), then reinstall re-stamps both markers

Defensive patterns

Strategy: validation

Validate before calling

import { readFileSync } from "node:fs";
function codexMarkersBalanced(path: string, pairs: [string, string][]): boolean {
  let src: string;
  try { src = readFileSync(path, "utf8"); } catch { return true; }
  return pairs.every(([b, e]) => {
    const bi = src.indexOf(b), ei = src.indexOf(e);
    return (bi === -1) === (ei === -1) && (bi === -1 || ei > bi);
  });
}

Try / catch

try { nativeInstallCodex(); } catch (e) {
  if (e instanceof Error && /Codex Caveman block is corrupted/.test(e.message)) {
    spawnSync("caveman", ["doctor", "codex"], { stdio: "inherit" });
    nativeInstallCodex();
  } else throw e;
}

Prevention

Delete Caveman marker blocks whole (BEGIN through END) when editing config.toml
Run caveman doctor codex after any manual cleanup of managed TOML
Review the full block before saving partial deletions

When it happens

Trigger: Native Codex install when config.toml contains a CODEX_NATIVE_ROOT_BEGIN or CODEX_NATIVE_TABLES_BEGIN marker without its matching END marker (asymmetric presence check per pair).

Common situations: Manual cleanup that deleted half the marked block; editor truncation; uninstall that removed only the END line; merge conflict resolution in dotfiles.

Related errors

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