JuliusBrussee/caveman · error · Error

registry output has no capabilities

Error message

registry output has no capabilities

What it means

Thrown while parsing the engine transform-registry output: after `registry_sha256` validates, the CLI requires `capabilities` to be a non-empty array. An empty or missing capabilities list means the engine reports no transforms at all, so candidate-plan generation has nothing to route through and the build refuses to proceed on that answer.

Source

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

    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(
      `cave_transform_registry_unavailable: run caveman setup or set CAVEMAN_ENGINE_BIN (${error instanceof Error ? error.message : String(error)})`,
    );
  }

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Run `caveman setup` to (re)install the engine and its transform registry.
2. Check the engine's registry command output manually to confirm `capabilities` is present and non-empty.
3. Align the engine binary and framework versions (`caveman doctor`); set `CAVEMAN_ENGINE_BIN` to the matching binary if multiple are installed.

Example fix

# before: engine registry empty
caveman-engine registry  # -> {"registry_sha256":"...","capabilities":[]}

# after
caveman setup             # reinstall transform pack
caveman-engine registry  # -> {"registry_sha256":"...","capabilities":[{"transform_id":"...",...}]}

function registryHasCapabilities(parsed: unknown): boolean {
  return Array.isArray((parsed as { capabilities?: unknown }).capabilities) &&
    ((parsed as { capabilities: unknown[] }).capabilities.length > 0);
}

function isNonEmptyCapabilityArray(v: unknown): v is Array<Record<string, unknown>> {
  return Array.isArray(v) && v.length > 0 && v.every((e) => typeof e === "object" && e !== null);
}

try {
  await build(args);
} catch (error) {
  if (error instanceof Error && error.message.startsWith("cave_transform_registry_unavailable")) {
    // empty capabilities: reinstall engine via caveman setup
  } else throw error;
}

When it happens

Trigger: The engine binary answers with `{ "registry_sha256": "..." }` and no `capabilities` key, or `capabilities: []`. Typical causes: an engine installed without its transform pack, a registry file that was emptied/corrupted locally, or an engine version that predates the capabilities field.

Common situations: Fresh engine install missing transform assets; an interrupted `caveman setup` leaving a zero-entry registry; version mismatch where an old engine speaks a smaller output schema.

Related errors

• registry output has no valid registry_sha256
• cave_transform_registry_unavailable: run caveman setup or se
• registry output has invalid capability
• engine_changed_bytes_without_recovery
• cave_unknown_transform:${transformID}

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