JuliusBrussee/caveman · error

cave_tool_result_requires_recovery

Error message

cave_tool_result_requires_recovery

What it means

Error "cave_tool_result_requires_recovery" thrown in JuliusBrussee/caveman.

Source

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

        if (raw.byteLength > maxInlineBytes) throw new Error("cave_tool_result_inline_limit");
        return {
          content: [{ type: "text", text: text ?? "null" }],
          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,

View on GitHub (pinned to 27d5a3981a)

Solutions

1. The tool result must carry recovery metadata; emit the result through the recovery-aware path.

When it happens

Trigger: Thrown at packages/agent/src/runtime.ts:3772 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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