JuliusBrussee/caveman · critical · Error

cave_${harness}_upstream_version_unresolvable

cave_${harness}_upstream_version_unresolvable

Error message

cave_${harness}_upstream_version_unresolvable

What it means

The adapter pins each harness to an exact upstream version (Vercel AI SDK 7.0.43, Eve 0.29.2, Mastra 1.55.0) and enforces the pin against what is ACTUALLY installed, resolved via `import.meta.resolve` of the package's own package.json. `cave_${harness}_upstream_version_unresolvable` means `installedPackageVersion(pkg)` returned `undefined`: the adapter could not read a version for the installed package at all, so pin enforcement is impossible and the call fails closed. A caller-claimed version can never substitute for the resolved one.

Source

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

    }
  } catch {
    // Not resolvable at all.
  }
  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");

View on GitHub (pinned to 27d5a3981a)

Solutions

  1. Install the exact pinned harness package in the runtime environment: `npm install ai@7.0.43` (or the Eve/Mastra pin shown in the adapter error's harness name).
  2. Verify resolution at runtime: `node -e "console.log(import.meta.resolve('ai/package.json'))"` from your app's entry; if it throws, fix the install layout.
  3. If you use a bundler, mark the harness package as external so `import.meta.resolve`/file reads still work.
  4. Re-run `pnpm install` after deleting lockfile-shadowed `node_modules` if the install is corrupted.

Example fix

// before: harness dependency pruned or never installed
// package.json deps: { "@caveman-ai/agent": "..." } // no "ai"

// after
// package.json
{
  "dependencies": {
    "@caveman-ai/agent": "...",
    "ai": "7.0.43"
  }
}
Defensive patterns

Strategy: validation

Validate before calling

import { createRequire } from "node:module";
function canResolveInstalledVersion(pkg: string): boolean {
  try {
    const resolved = import.meta.resolve(`${pkg}/package.json`);
    return typeof resolved === "string";
  } catch {
    try {
      createRequire(import.meta.url).resolve(pkg);
      return true;
    } catch {
      return false;
    }
  }
}
if (!canResolveInstalledVersion("ai")) throw new Error("install ai@7.0.43 before running");

Try / catch

try {
  await adapter.run(request);
} catch (err) {
  if (err instanceof Error && err.message.endsWith("_upstream_version_unresolvable")) {
    // dependency resolution failed: fix the install, surface a setup error to the operator
  }
}

Prevention

When it happens

Trigger: The harness package (`ai`, `@eve/...`, or `@mastra/*`) is not installed in the runtime resolving the adapter; its package.json cannot be read (permissions, corrupted install); the package's exports map hides `package.json` AND the fallback walk-up from the entry file fails; pnpm/yarn PnP layouts that defeat both resolution paths.

Common situations: Deploying to an environment where the adapter package was bundled/externalized but the harness dependency was pruned by tree-shaking or `--production` install pruning; a corrupted node_modules after an interrupted install; a bundler (esbuild/webpack) rewriting `import.meta.resolve` so it throws at runtime; missing optional peer dependency that was never installed.

Related errors

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