What causes "registry output has no valid registry_sha256" in JuliusBrussee/caveman?

Run the registry command manually (`$CAVEMAN_ENGINE_BIN ` or `caveman-engine`) and inspect stdout — `registry_sha256` must be exactly 64 lowercase hex chars.

JuliusBrussee/caveman · error · Error

registry output has no valid registry_sha256

Error message

registry output has no valid registry_sha256

What it means

Thrown while parsing the output of the caveman engine's transform-registry command. The CLI spawns the engine binary (10s timeout, 2 MiB buffer), JSON-parses stdout, and requires `registry_sha256` to be a string matching `^[0-9a-f]{64}$`. If the field is missing, not a string, or not a 64-char lowercase hex digest, this error is thrown. A matching failure is wrapped into `cave_transform_registry_unavailable` by the outer catch.

Source

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

  const command = process.env.CAVEMAN_ENGINE_BIN ?? "caveman-engine";
  try {
    const env = buildEngineEnv();
    const invocation = portableInvocation(command, ["registry"], { env });
    const { stdout } = await execFileAsync(invocation.command, [...invocation.args], {
      encoding: "utf8",
      env,
      maxBuffer: 2 << 20,
      timeout: 10_000,
    });
    const parsed = JSON.parse(stdout) as {
      registry_sha256?: unknown;
      capabilities?: Array<{
        transform_id?: unknown;
        eligible_segment_kinds?: unknown;
      }>;
    };
    if (typeof parsed.registry_sha256 !== "string" || !/^[0-9a-f]{64}$/.test(parsed.registry_sha256)) {
      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(

View on GitHub (pinned to 27d5a3981a)

Solutions

Run the registry command manually (`$CAVEMAN_ENGINE_BIN <registry args>` or `caveman-engine`) and inspect stdout — `registry_sha256` must be exactly 64 lowercase hex chars.
Reinstall/refresh the engine with `caveman setup` so the binary matches the framework version.
If a wrapper or shim adds stdout noise, point `CAVEMAN_ENGINE_BIN` at the real binary.
Verify engine and framework versions agree via `caveman doctor`.

Example fix

# before: shim pollutes stdout
CAVEMAN_ENGINE_BIN=./engine-shim.sh

# after: point at the real binary
CAVEMAN_ENGINE_BIN=/usr/local/bin/caveman-engine

Defensive patterns

Strategy: validation

Validate before calling

function isValidRegistrySha256(v: unknown): boolean {
  return typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
}
// before building, probe the engine once and assert isValidRegistrySha256(parsed.registry_sha256)

Type guard

function isHex64(v: unknown): v is string {
  return typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
}

Try / catch

try {
  await build(args);
} catch (error) {
  if (error instanceof Error && error.message.startsWith("cave_transform_registry_unavailable")) {
    // inspect the parenthesized cause: bad registry_sha256 means engine/framework schema mismatch -> caveman setup
  } else throw error;
}

Prevention

Install the engine via `caveman setup` and keep it version-locked with the framework.
Never wrap the engine binary in a script that writes to stdout.
Run `caveman doctor` after engine changes.

When it happens

Trigger: `CAVEMAN_ENGINE_BIN` (or the default `caveman-engine` on PATH) resolves to a binary that prints JSON without a valid `registry_sha256`: a different tool by the same name, an engine version with a changed output schema, a shell shim that prepends banner text making the JSON parse land elsewhere, or a partial/errored engine output.

Common situations: A stale engine from before an output-schema change; PATH shadowing by an unrelated `caveman-engine`; a wrapper script that logs to stdout before the JSON; a truncated registry file inside a broken engine install.

Related errors

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