JuliusBrussee/caveman · error · TypeError

Unknown Caveman adapter

Error message

Unknown Caveman adapter: ${adapter}

What it means

inspectFrameworkCompatibility looks up the adapter name in the adapters registry; if the key is absent it throws this TypeError. Only registered Caveman adapter names (e.g. 'langchain') can be inspected. This is a programmer-error guard against typos or unsupported adapters.

Solutions

1. Check the spelling and exact casing of the adapter string against the adapters registry exported by the package.
2. List available adapters by inspecting the adapters export (or package docs) and pick a valid AdapterName.
3. Upgrade @caveman/middleware if the adapter exists only in a newer release.
4. Validate adapter names from external input against the registry before calling the function.

Example fix

// before
inspectFrameworkCompatibility('langchain-js'); // TypeError
// after
const adapter: AdapterName = 'langchain';
inspectFrameworkCompatibility(adapter);

import { adapters } from '@caveman/middleware/typescript/compatibility';
function isValidAdapter(a: string): a is AdapterName { return a in adapters; }

const isAdapterName = (v: unknown): v is AdapterName =>
  typeof v === 'string' && v in adapters;

try {
  inspectFrameworkCompatibility(adapter);
} catch (e) {
  if (e instanceof TypeError && e.message.startsWith('Unknown Caveman adapter')) {
    throw new Error(`Unsupported adapter '${adapter}'; expected one of: ${Object.keys(adapters).join(', ')}`);
  } else throw e;
}

When it happens

Trigger: Calling inspectFrameworkCompatibility(adapter) with an adapter string that is not a key of the adapters registry — typically a typo, an adapter for another library version, or a dynamically constructed name.

Common situations: Typos like 'langchainjs' or 'LangChain', passing user-supplied adapter names without validation, or using an adapter added in a newer package version than installed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• artifactId is required
• assemble requires model and sessionId
• cave artifact response missing artifact_id
• cave checkpoint response missing source_ref or messages
• cave_harness_adapter_version_invalid

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/bca30ce975195e6c. Report an issue: GitHub.

Appendix: source

Thrown at packages/middleware/typescript/src/compatibility.ts:64

}

export function frameworkCompatible(name: Framework, version = frameworkVersion(name)): boolean {
  const spec = frameworks[name];
  return inRange(version, spec.tested, spec.high);
}

export function adapterCompatible(adapter: AdapterName): boolean {
  return adapters[adapter].every(name => frameworkCompatible(name));
}

/** Read-only, content-free local check. Does not import optional frameworks or
 * contact the compression runtime. Unknown metadata never enables compression.
 * Node ESM bundles must keep framework packages external with metadata intact. */
export function inspectFrameworkCompatibility(adapter: AdapterName): {
  schema_version: 1; adapter: AdapterName; compatible: boolean; frameworks: FrameworkCompatibility[];
} {
  const entries = adapters[adapter];
  if (!entries) throw new TypeError(`Unknown Caveman adapter: ${adapter}`);
  const checks: FrameworkCompatibility[] = entries.map(name => {
    const spec = frameworks[name], version = frameworkVersion(name);
    const compatible = frameworkCompatible(name, version), tested = version === spec.tested;
    const reason = compatible ? 'compatible' : version === null ? 'version_unavailable' : 'unsupported_version';
    const action = compatible
      ? tested ? 'Exact test pin detected; run your workload acceptance checks.' : `Range accepted; only ${spec.tested} is the tested pin. Run your workload acceptance checks.`
      : version === null
        ? `Install ${name}@${spec.tested}. For Node ESM bundles, keep framework packages external and preserve package.json metadata.`
        : `Use ${name}@${spec.tested}, or keep optimization bypassed until this version is supported.`;
    return { package: name, installed_version: version, supported_range: `>=${spec.tested} <${spec.high}`,
      tested_version: spec.tested, tested, compatible, reason, action };
  });
  return { schema_version: 1, adapter, compatible: checks.every(check => check.compatible), frameworks: checks };
}

View on GitHub (pinned to 3ee70a1026)