JuliusBrussee/caveman · critical

cave_tool_result_recovery_mismatch

cave_tool_result_recovery_mismatch

Error message

cave_tool_result_recovery_mismatch

What it means

After offloading a tool result, the runtime reads the payload back with engineRetrieve and byte-compares it with the original. A mismatch means the compress/store/retrieve round trip corrupted the data, so the runtime fails loudly rather than feeding the model altered content.

Solutions

  1. Retry the tool call — a transient storage glitch often resolves on retry.
  2. Verify the engine binary version matches what the runtime expects and reinstall/upgrade it.
  3. Clear the engine's cache/artifact store and rerun.
  4. Check for concurrent invocations sharing one recovery store and isolate per-invocation state.

Example fix

// before: shared engine store across concurrent runs
const a = createRuntime({ engineBin, storePath });
const b = createRuntime({ engineBin, storePath });
// after: isolated store per runtime
const a = createRuntime({ engineBin, storePath: "/tmp/store-a" });
const b = createRuntime({ engineBin, storePath: "/tmp/store-b" });
Defensive patterns

Strategy: retry

Validate before calling

// post-hoc self check you can run in your own tool wrapper
const round = await engineRetrieve((await engineCompress(payload, engineBin)).handle, undefined, engineBin);
if (!bytesEqual(round, payload)) console.warn('engine round-trip mismatch detected');

Try / catch

try {
  return await callTool(args);
} catch (e) {
  if (e?.message === 'cave_tool_result_recovery_mismatch') {
    await verifyEngineInstall();
    return retryOnce(() => callTool(args));
  }
  throw e;
}

Prevention

When it happens

Trigger: bytesEqual(engineRetrieve(transformed.handle, undefined, engineBin), raw) returns false after engineCompress at runtime.ts:3775.

Common situations: Corrupted engine cache/storage; concurrent invocations overwriting the same handle space; an engine binary bug or version incompatibility; disk corruption in the artifact store.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at packages/agent/src/runtime.ts:3775

          details: { effect: definition.effect, resultPolicy: definition.result },
        };
      }
      const mustOffload = definition.result === "page" ||
        definition.result === "compress" ||
        definition.result === "exact_ccr" ||
        raw.byteLength > maxInlineBytes;
      if (!mustOffload) {
        return {
          content: [{ type: "text", text: text ?? "null" }],
          details: { effect: definition.effect, resultPolicy: definition.result },
        };
      }
      const transformed = await engineCompress(raw, engineBin);
      if (!transformed.handle || !recoveryHandles) {
        throw new Error("cave_tool_result_requires_recovery");
      }
      const recovered = await engineRetrieve(transformed.handle, undefined, engineBin);
      if (!bytesEqual(recovered, raw)) throw new Error("cave_tool_result_recovery_mismatch");
      recoveryHandles.add(transformed.handle);
      const compressed = new TextDecoder().decode(transformed.output);
      return {
        content: [{
          type: "text",
          text: [
            compressed,
            `<<cave_retrieve:${transformed.handle}>>`,
            definition.result === "page"
              ? "Use cave_retrieve with a narrow query to page relevant detail."
              : "Use cave_retrieve for omitted detail.",
          ].join("\n"),
        }],
        details: {
          effect: definition.effect,
          resultPolicy: definition.result,
          recoveryHandle: transformed.handle,
          recoveryVerified: true,

View on GitHub (pinned to 3ee70a1026)