JuliusBrussee/caveman · error

cave_unknown_transform:${transformID}

Error message

cave_unknown_transform:${transformID}

What it means

Thrown by engineContentType when a transform ID does not match the caveman.engine.<name>.v1 pattern, so no engine content type can be derived. This guards the engine-invocation layer, complementing the known-set check in plan application.

Source

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

  const handle = typeof report.recovery_handle === "string" && report.recovery_handle.length > 0
    ? report.recovery_handle
    : undefined;
  if (!handle && !bytesEqual(result.stdout, input)) {
    throw new Error("engine_changed_bytes_without_recovery");
  }
  const tokensBefore = validEngineTokenCount(report.tokens_before);
  const tokensAfter = validEngineTokenCount(report.tokens_after);
  return {
    output: result.stdout,
    ...(handle === undefined ? {} : { handle }),
    ...(tokensBefore === undefined ? {} : { tokensBefore }),
    ...(tokensAfter === undefined ? {} : { tokensAfter }),
  };
}

function engineContentType(transformID: string): string {
  const match = /^caveman\.engine\.([a-z0-9-]+)\.v1$/.exec(transformID);
  if (!match) throw new Error(`cave_unknown_transform:${transformID}`);
  return match[1]!;
}


export interface SegmentRecoveryProof {
  transformID: string;
  /**
   * `recovered` = the engine returned bytes identical to the original.
   * `not_smaller` = the engine declined to compress, so there is nothing to
   * recover and the original bytes are what the model sees.
   * `mismatch` = recovery did not reproduce the original; the plan fails open
   * to the original body and nothing may be claimed for this segment.
   */
  outcome: "recovered" | "not_smaller" | "mismatch";
  handle?: string;
  originalSHA256: string;
  recoveredSHA256?: string;
  originalBytes: number;

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Use canonical transform IDs of the form caveman.engine.<type>.v1
2. Route all transform selection through plan validation (the known-set check) rather than calling engine helpers directly
3. Fix any renamed constants so the full dotted form is preserved

Example fix

// before
engineContentType("text"); // throws

// after
engineContentType("caveman.engine.text.v1");

const ENGINE_ID = /^caveman\.engine\.([a-z0-9-]+)\.v1$/;
function isEngineTransformId(id: string): boolean {
  return ENGINE_ID.test(id);
}

function isEngineTransform(id: string): id is `caveman.engine.${string}.v1` {
  return /^caveman\.engine\.[a-z0-9-]+\.v1$/.test(id);
}

if (!isEngineTransform(transformID)) throw new TypeError(`not an engine transform: ${transformID}`);
await engineContentType(transformID);

When it happens

Trigger: Passing a transformID that is not of the form caveman.engine.<lowercase-alnum-dash>.v1 to engineContentType — e.g. an internal call with a raw engine name ('text') or a fully-custom id.

Common situations: Custom transform IDs bypassing plan validation; refactors renaming transform ID constants; calling internal engine helpers directly with unvalidated ids.

Related errors

• registry output has invalid capability
• option not found
• cave_harness_adapter_version_invalid
• cave_harness_model_invalid
• cave_harness_model_identity_missing

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