JuliusBrussee/caveman · error

cave_context_ir_invalid

cave_context_ir_invalid

Error message

cave_context_ir_invalid

What it means

contextIRFromWire validates an untrusted wire value before reconstructing a ContextIR. The top-level envelope must be a record with exactly the keys schema_version and segments, schema_version must be 1, and segments must be an array; any deviation throws cave_context_ir_invalid.

Solutions

1. Ensure the payload has exactly schema_version: 1 and an array segments field with no extra keys
2. Regenerate the wire payload with contextIRToWire from a valid ContextIR
3. Wrap the call in try/catch and fall back to rebuilding the IR from origin data

Example fix

// before
const ir = contextIRFromWire({ segments: [] });
// after
const ir = contextIRFromWire({ schema_version: 1, segments: [] });

function looksLikeWire(v: unknown): boolean {
  return typeof v === "object" && v !== null &&
    Object.keys(v).sort().join() === "schema_version,segments" &&
    (v as any).schema_version === 1 && Array.isArray((v as any).segments);
}
if (!looksLikeWire(payload)) throw new Error("payload is not a v1 ContextIR wire object");

const isIRWire = (v: unknown): v is ContextIRWire =>
  typeof v === "object" && v !== null &&
  Object.keys(v).length === 2 &&
  (v as any).schema_version === 1 && Array.isArray((v as any).segments);

try {
  const ir = contextIRFromWire(payload);
} catch (err) {
  if ((err as Error).message === "cave_context_ir_invalid") {
    console.error("Discarding malformed ContextIR payload; rebuilding from origin");
    ir = rebuildFromOrigin();
  } else throw err;
}

When it happens

Trigger: Feeding a wire payload missing schema_version or segments; payloads with extra/renamed keys; schema_version other than 1; segments not an array (null, object, string) — typically from corrupt caches or tampered network data.

Common situations: Truncated JSON cache files that parse as valid JSON but wrong shape; API responses from a service writing a different schema; hand-edited fixture files in tests.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• canonical span
• cave_agent_definition_invalid
• cave_output_schema_mismatch
• cave_output_schema_mismatch
• cave_sandbox_request_invalid

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

Appendix: source

Thrown at packages/agent/src/context-ir.ts:85

      stability: segment.stability,
      safety: segment.safety,
      priority: segment.priority,
      recovery: segment.recovery,
      cache_region: segment.cacheRegion,
      privacy: segment.privacy,
      opaque: segment.opaque,
      ...(segment.ttlTurns === undefined ? {} : { ttl_turns: segment.ttlTurns }),
      provenance_digest: segment.provenanceDigest,
      token_count: segment.tokenCount,
      body_handle: segment.bodyHandle,
    })),
  };
}

export function contextIRFromWire(value: unknown): ContextIR {
  if (!isRecord(value) || !exactKeys(value, ["schema_version", "segments"]) ||
      value.schema_version !== 1 || !Array.isArray(value.segments)) {
    throw new Error("cave_context_ir_invalid");
  }
  const segments = value.segments.map((item): ContextSegment => {
    const required = [
      "id", "kind", "stability", "safety", "priority", "recovery", "cache_region",
      "privacy", "opaque", "provenance_digest", "token_count", "body_handle",
    ];
    if (!isRecord(item) ||
        !(exactKeys(item, required) || exactKeys(item, [...required, "ttl_turns"])) ||
        typeof item.id !== "string" || item.id.length === 0 ||
        !known(item.kind, ["instruction", "user_intent", "tool_schema", "skill", "memory", "history", "tool_result", "artifact", "error", "output_contract"]) ||
        !known(item.stability, ["build", "session", "turn"]) ||
        !known(item.safety, ["S0", "S1", "S2", "S3", "S4"]) ||
        !known(item.priority, ["required", "high", "normal", "low"]) ||
        !known(item.recovery, ["none", "exact_ccr", "source_ref", "recompute"]) ||
        !known(item.cache_region, ["frozen_prefix", "live_zone", "uncached"]) ||
        !known(item.privacy, ["content_blind", "local_sensitive", "connected_allowed"]) ||
        typeof item.opaque !== "boolean" ||
        !/^[0-9a-f]{64}$/.test(String(item.provenance_digest)) ||

View on GitHub (pinned to 3ee70a1026)