JuliusBrussee/caveman · error

cave_context_ir_unknown_schema

cave_context_ir_unknown_schema

Error message

cave_context_ir_unknown_schema

What it means

contextIRToWire serializes a ContextIR to its wire form and only understands schema_version 1. If the IR was produced by a different schema version (e.g. newer library writing v2 read by v1), it throws cave_context_ir_unknown_schema rather than guessing.

Solutions

1. Upgrade/downgrade packages so both producer and consumer use schema version 1
2. Rebuild the ContextIR from source data instead of reusing a stale persisted IR
3. Fix hand-constructed IR objects to set schemaVersion: 1

Example fix

// before
const ir = { schemaVersion: 2, segments: [] } as unknown as ContextIR;
contextIRToWire(ir);
// after
const ir: ContextIR = { schemaVersion: 1, segments: [] };
contextIRToWire(ir);

if (ir.schemaVersion !== 1) {
  throw new Error(`Unsupported ContextIR schema ${ir.schemaVersion}; regenerate with a v1-compatible library`);
}

const isV1IR = (ir: { schemaVersion?: unknown }): ir is ContextIR => ir.schemaVersion === 1;

try {
  const wire = contextIRToWire(ir);
} catch (err) {
  if ((err as Error).message === "cave_context_ir_unknown_schema") {
    console.error("ContextIR schema version mismatch; rebuild the IR or align package versions");
  } else throw err;
}

When it happens

Trigger: Passing a ContextIR whose schemaVersion is not 1; deserializing persisted IR from a different library version into a v1-expecting contextIRToWire; hand-constructing an IR object with a wrong or missing schemaVersion.

Common situations: Version skew: persisted context caches written by a newer caveman release read by an older one; copying IR structs between services with mismatched package versions.

Related errors

• session-value artifact schema mismatch
• unsupported bundle schema
• unsupported_version
• unsupported_version
• assembly slot content is not JSON-serializable

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

Appendix: source

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

  safety: SafetyClass;
  priority: ContextPriority;
  recovery: RecoveryKind;
  cache_region: CacheRegion;
  privacy: PrivacyClass;
  opaque: boolean;
  ttl_turns?: number;
  provenance_digest: string;
  token_count: number;
  body_handle: string;
}

export interface ContextIRWire {
  schema_version: 1;
  segments: ContextSegmentWire[];
}

export function contextIRToWire(ir: ContextIR): ContextIRWire {
  if (ir.schemaVersion !== 1) throw new Error("cave_context_ir_unknown_schema");
  return {
    schema_version: 1,
    segments: ir.segments.map((segment) => ({
      id: segment.id,
      kind: segment.kind,
      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,
    })),
  };

View on GitHub (pinned to 3ee70a1026)