JuliusBrussee/caveman · error · Error

cave_harness_upstream_version_mismatch

cave_harness_upstream_version_mismatch

Error message

cave_harness_upstream_version_mismatch

What it means

After a completed Eve run, the adapter extracts runtime identity from the (single) `session.started` event and compares its reported `eveVersion` against `request.build.harness.upstream_version` — the Eve version pinned in the Cave build lock. A mismatch means the session was actually served by a different Eve version than the locked build was compiled against, so all downstream evidence (usage, model identity) would be untrustworthy, and the adapter throws before reading usage.

Solutions

1. Regenerate the build lock against the currently deployed Eve version so `build.harness.upstream_version` matches the runtime
2. Align Eve versions across environments, or finish rolling upgrades before running locked executions
3. If the lock pin is intentional, deploy the Eve runtime at exactly that pinned version

Example fix

// before — lock built when the gateway ran 0.29.1, runtime now reports 0.29.2
// build.harness.upstream_version: "0.29.1"
// after — rebuild the lock against the live runtime
// build.harness.upstream_version: "0.29.2"

// probe the live runtime's version and compare to the lock before locked runs
const probe = await session.send({ message: 'ping' });
const started = (await probe.result()).events
  .find((ev) => (ev as { type?: string })?.type === 'session.started');
const eveVersion = started?.data?.runtime?.eveVersion;
if (eveVersion !== lock.harness.upstream_version) {
  throw new Error(`eve lock drift: lock=${lock.harness.upstream_version} runtime=${eveVersion}`);
}

When it happens

Trigger: Build lock generated when the gateway ran Eve 0.29.1 while the live session reports 0.29.2; a rolling Eve deployment serving mixed versions across requests; a checked-in lock file gone stale after an upgrade.

Common situations: Stale lock after an Eve upgrade; lock generated in CI against a different Eve deployment than production; long-lived cached locks that nobody regenerates on release.

Related errors

• cave_eve_runtime_identity_missing
• cave_eve_terminal_${result.status}
• cave_eve_usage_missing
• cave_harness_build_mismatch
• cave_stale_lock: : run npm run build to relock

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/3807aa3064eab214. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/adapters.ts:260

  session: EveSessionBinding,
): HarnessAdapter {
  assertSupportedUpstream(identity, EVE_VERSION, "eve", "eve");
  return createHarnessAdapter("eve", identity, {
    package: "eve/client",
    class: "ClientSession",
    method: "send.result",
    usage: "step.completed.data.usage",
  }, async (request) => {
    const startedAt = performance.now();
    const response = await session.send({
      message: request.prompt,
      ...(request.signal === undefined ? {} : { signal: request.signal }),
    });
    const result = await response.result();
    if (result.status !== "completed") throw new Error(`cave_eve_terminal_${result.status}`);
    const identity = eveRuntimeIdentity(result.events);
    if (identity.upstreamVersion !== request.build.harness.upstream_version) {
      throw new Error("cave_harness_upstream_version_mismatch");
    }
    const usage = usageFromEveEvents(result.events, request.plan.reasoning !== "none");
    return harnessExecution({
      request,
      text: result.message ?? "",
      provider: identity.provider,
      model: identity.model,
      usage,
      latencyMs: Math.round(performance.now() - startedAt),
    });
  });
}

export interface MastraAgentBinding {
  generate(messages: string, options?: {
    maxProcessorRetries?: number;
    maxSteps?: number;
    runId?: string;

View on GitHub (pinned to 766dce6b13)