JuliusBrussee/caveman · error · Error

unknown adapter failure must preserve original bytes

Error message

unknown adapter failure must preserve original bytes

What it means

Thrown by the shared-contracts validation script when the static agent contract fixture for the Claude adapter does not declare failure_fallback: "original". The contract encodes a hard requirement: when an adapter encounters an unknown input, it must pass the original bytes through untouched rather than dropping or transforming them. Any deviation breaks the byte-preservation guarantee the adapter layer promises to callers.

Source

Thrown at packages/shared/contracts/scripts/validate-schemas.mjs:82

for (const key of [
  "normalized_context_digest",
  "plan_sha256",
  "ordered_transform_ids",
  "provider_visible_digest",
  "recovery_handles",
  "accounting_method",
  "failure_fallback",
]) {
  if (JSON.stringify(claude[key]) !== JSON.stringify(pi[key])) {
    throw new Error(`agent conformance mismatch: ${key}`);
  }
}
if (claude.build_sha256 === pi.build_sha256) {
  throw new Error("adapter-specific build_sha256 values must differ");
}
if (claude.failure_fallback !== "original") {
  throw new Error("unknown adapter failure must preserve original bytes");
}

console.log(
  `validated ${files.length} JSON schemas and ${fixtureFiles.length} static agent contract fixtures (not executable parity)`,
);

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Open the claude agent contract fixture JSON referenced by the script and set "failure_fallback": "original".
2. If you intentionally changed adapter fallback behavior, revert that behavior instead — the contract test is asserting byte preservation on unknown input, which is the intended semantics.
3. Re-run the validation script to confirm the whole fixture set passes, including the build_sha256-must-differ and conformance-key checks above this throw.

Example fix

// fixtures/claude.json
// before
{
  "failure_fallback": "drop"
}
// after
{
  "failure_fallback": "original"
}

// Before committing fixture changes:
const claude = JSON.parse(readFileSync("claude.fixture.json", "utf8"));
if (claude.failure_fallback !== "original") {
  console.error("fixture must keep failure_fallback === 'original'");
  process.exit(1);
}

When it happens

Trigger: Running packages/shared/contracts/scripts/validate-schemas.mjs (usually via CI or a repo test script) after someone edited the claude fixture JSON so that failure_fallback is missing, set to "drop", "error", or any value other than the exact string "original".

Common situations: A developer adds a new fallback mode to an adapter and updates the fixture to match; a merge conflict resolution picks the wrong fixture value; someone regenerates fixtures with a tool that normalizes or omits the field.

Related errors

• cave_mastra_usage_missing
• cave_eve_usage_missing
• no provider credential detected; pass --provider

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