JuliusBrussee/caveman · error · Error

cave_${harness}_upstream_version_unsupported

cave_${harness}_upstream_version_unsupported

Error message

cave_${harness}_upstream_version_unsupported

What it means

The installed version of the harness package was resolved successfully but does not equal the exact version this adapter build pins and validates against (e.g. Vercel AI SDK must be 7.0.43, Eve 0.29.2, Mastra 1.55.0). Because wire contracts and usage shapes differ across upstream versions, the adapter refuses to run on any other installed version — a semver-compatible newer release is still rejected. This check runs against the installed package.json version, so what is on disk decides, not what the caller claims.

Source

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

  }
  return undefined;
}

function assertSupportedUpstream(
  identity: HarnessAdapterIdentity,
  expected: string,
  harness: string,
  pkg: string,
): void {
  // The pin is enforced against the INSTALLED version, and the caller's claimed
  // upstreamVersion must match what is actually installed — a claim alone can no
  // longer authorize execution.
  const installed = installedPackageVersion(pkg);
  if (installed === undefined) {
    throw new Error(`cave_${harness}_upstream_version_unresolvable`);
  }
  if (installed !== expected) {
    throw new Error(`cave_${harness}_upstream_version_unsupported`);
  }
  if (identity.upstreamVersion !== installed) {
    throw new Error(`cave_${harness}_upstream_version_mismatch`);
  }
}

function canonicalRecord(value: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> {
  let encoded: string;
  try {
    encoded = stableStringify(value);
  } catch {
    throw new Error("cave_harness_wire_contract_invalid");
  }
  const decoded = JSON.parse(encoded) as unknown;
  if (!isRecord(decoded)) throw new Error("cave_harness_wire_contract_invalid");
  return decoded;
}

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Pin the harness package to the exact version named in the error context, e.g. `npm install --save-exact ai@7.0.43` (or Eve 0.29.2 / Mastra 1.55.0 per the harness name in the error).
2. Check for duplicate installations: `npm ls ai` and remove the extraneous copy.
3. Commit the lockfile and reinstall from scratch (`rm -rf node_modules && npm ci`) so the pinned version actually resolves.
4. If you need a newer harness version, upgrade `@caveman-ai/agent` to a build whose pin matches it.

Example fix

// before: package.json
"dependencies": { "ai": "^7.0.43" } // resolves to 7.0.55 -> throws

// after: package.json
"dependencies": { "ai": "7.0.43" } // exact pin, resolves to 7.0.43

import { readFileSync } from "node:fs";
function assertPinnedVersion(pkg: string, expected: string): void {
  const path = fileURLToPath(import.meta.resolve(`${pkg}/package.json`));
  const installed = JSON.parse(readFileSync(path, "utf8")).version;
  if (installed !== expected) {
    throw new Error(`${pkg}: expected ${expected}, installed ${installed} — fix before run`);
  }
}

try {
  await adapter.run(request);
} catch (err) {
  if (err instanceof Error && err.message.endsWith("_upstream_version_unsupported")) {
    // fail fast at startup instead: check versions in a preflight, never auto-retry
  }
}

When it happens

Trigger: Running `npm install ai@latest` (or a floating `^7.0.43` range that resolved to 7.0.x) alongside the adapter; a lockfile update or `npm update` bumping the harness package; a shared monorepo hoisting a different version of `ai`/`@mastra/core` into the resolution path than the app expects.

Common situations: Fresh clone where a teammate regenerated the lockfile with looser ranges; adding another dependency that also depends on `ai` with a different version, causing hoisting of the wrong copy; CI caching an old node_modules then installing over it.

Related errors

• cave_${harness}_upstream_version_unresolvable
• cave_${harness}_upstream_version_mismatch
• cave_harness_model_invalid
• cave_harness_model_identity_missing
• cave_harness_wire_contract_invalid

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