JuliusBrussee/caveman · error · Error

cave_transform_registry_unavailable: run caveman setup or se

Error message

cave_transform_registry_unavailable: run caveman setup or set CAVEMAN_ENGINE_BIN (${error instanceof Error ? error.message : String(error)})

What it means

Catch-all wrapper around the whole transform-registry load: spawning the engine binary, its timeout (10s), non-zero exit, stdout too large (>2 MiB), invalid JSON, or any of the per-field validation errors above. The message tells you the two supported remedies — run `caveman setup` to install the engine, or point `CAVEMAN_ENGINE_BIN` at an existing binary — and appends the underlying error text for diagnosis.

Source

Thrown at packages/agent/src/cli.ts:1132

      throw new Error("registry output has no valid registry_sha256");
    }
    if (!Array.isArray(parsed.capabilities) || parsed.capabilities.length === 0) {
      throw new Error("registry output has no capabilities");
    }
    const capabilities = parsed.capabilities.map((capability): TransformCapability => {
      if (typeof capability.transform_id !== "string" ||
          !Array.isArray(capability.eligible_segment_kinds) ||
          capability.eligible_segment_kinds.some((kind) => typeof kind !== "string")) {
        throw new Error("registry output has invalid capability");
      }
      return {
        transformID: capability.transform_id,
        segmentKinds: capability.eligible_segment_kinds as TransformCapability["segmentKinds"],
      };
    });
    return { sha256: parsed.registry_sha256, capabilities };
  } catch (error) {
    throw new Error(
      `cave_transform_registry_unavailable: run caveman setup or set CAVEMAN_ENGINE_BIN (${error instanceof Error ? error.message : String(error)})`,
    );
  }
}

async function engineEntitled(): Promise<boolean> {
  const command = process.env.CAVEMAN_CLI_BIN ?? "caveman";
  try {
    const env = buildRuntimeControlEnv();
    const invocation = portableInvocation(command, ["status", "--json"], { env });
    const { stdout } = await execFileAsync(invocation.command, [...invocation.args], {
      encoding: "utf8",
      env,
      maxBuffer: 2 << 20,
      timeout: 10_000,
    });
    const parsed = JSON.parse(stdout) as { mode?: unknown; seat?: { entitled?: unknown } };
    return parsed.seat?.entitled === true && parsed.mode === "compress";

View on GitHub (pinned to 27d5a3981a)

Solutions

Run `caveman setup` to install/repair the engine and registry.
If the engine exists elsewhere, set `CAVEMAN_ENGINE_BIN=/path/to/caveman-engine`.
Read the parenthesized cause: ENOENT → missing binary; timeout → pre-warm the engine once manually; SyntaxError → binary prints non-JSON output.
Verify with `caveman doctor` that the engine registry check passes before building.

Example fix

# before
npm run build
# Error: cave_transform_registry_unavailable: ... spawn caveman-engine ENOENT

# after
caveman setup
# or: export CAVEMAN_ENGINE_BIN=/opt/caveman/bin/caveman-engine
npm run build

Defensive patterns

Strategy: retry

Validate before calling

import { access } from "node:fs/promises";

async function engineAvailable(): Promise<boolean> {
  const bin = process.env.CAVEMAN_ENGINE_BIN ?? "caveman-engine";
  if (process.env.CAVEMAN_ENGINE_BIN) {
    try { await access(process.env.CAVEMAN_ENGINE_BIN); return true; } catch { return false; }
  }
  return false; // fall back to `command -v caveman-engine` in shell

Try / catch

try {
  await build(args);
} catch (error) {
  if (error instanceof Error && error.message.startsWith("cave_transform_registry_unavailable")) {
    // read the cause: ENOENT -> set CAVEMAN_ENGINE_BIN or run caveman setup; timeout -> pre-warm engine; then retry once
  } else throw error;
}

Prevention

Run `caveman setup` as part of environment provisioning (devcontainer, CI image).
Set CAVEMAN_ENGINE_BIN explicitly in CI to avoid PATH surprises.
Pre-warm the engine once on cold runners to avoid the 10s first-start timeout.

When it happens

Trigger: `caveman-engine` not on PATH and `CAVEMAN_ENGINE_BIN` unset (spawn ENOENT); the engine exceeds the 10-second timeout on first-run initialization; engine exits non-zero (broken install); stdout is not JSON (crash traceback); any of the registry_sha256/capabilities validation failures.

Common situations: Fresh machine without `caveman setup`; CI container missing the engine; corporate environment blocking engine download; slow cold start of the engine exceeding 10s on constrained runners; `CAVEMAN_ENGINE_BIN` pointing at a removed path.

Related errors

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