JuliusBrussee/caveman · error · Error

registry output has invalid capability

Error message

registry output has invalid capability

What it means

Thrown per-entry while mapping the engine registry's `capabilities` array into `TransformCapability` objects. Each capability must have a string `transform_id` and an `eligible_segment_kinds` array whose every element is a string. Any entry violating that shape fails the whole registry load (and is then wrapped into `cave_transform_registry_unavailable` by the outer catch).

Source

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

    });
    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)})`,
    );
  }
}

async function engineEntitled(): Promise<boolean> {
  const command = process.env.CAVEMAN_CLI_BIN ?? "caveman";
  try {
    const env = buildRuntimeControlEnv();

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Inspect the engine registry JSON and remove or fix the malformed capability entry.
2. Reinstall the engine (`caveman setup`) to restore a known-good registry.
3. Ensure the engine version matches the framework's expected registry schema; pin both together.

Example fix

// before: malformed entry
{ "transform_id": 42, "eligible_segment_kinds": ["static"] }

// after
{ "transform_id": "caveman.engine.text.v1", "eligible_segment_kinds": ["static"] }

function isValidCapability(v: unknown): boolean {
  return typeof v === "object" && v !== null &&
    typeof (v as { transform_id?: unknown }).transform_id === "string" &&
    Array.isArray((v as { eligible_segment_kinds?: unknown }).eligible_segment_kinds) &&
    ((v as { eligible_segment_kinds: unknown[] }).eligible_segment_kinds.every((k) => typeof k === "string"));
}

function isTransformCapability(v: unknown): v is { transform_id: string; eligible_segment_kinds: string[] } {
  return typeof v === "object" && v !== null &&
    typeof (v as { transform_id?: unknown }).transform_id === "string" &&
    Array.isArray((v as { eligible_segment_kinds?: unknown }).eligible_segment_kinds) &&
    (v as { eligible_segment_kinds: unknown[] }).eligible_segment_kinds.every((k) => typeof k === "string");
}

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

When it happens

Trigger: An engine registry payload where a capability has a numeric or null `transform_id`, `eligible_segment_kinds` is missing/an object, or contains non-string kinds. Usually an engine/framework schema mismatch or hand-edited/corrupted registry data inside the engine's install.

Common situations: Engine binary from a different release train than the CLI package; registry files edited or partially written after a crash; third-party transforms installed into the engine with malformed manifests.

Related errors

• registry output has no valid registry_sha256
• registry output has no capabilities
• cave_unknown_transform:${transformID}
• option not found
• cave_harness_adapter_version_invalid

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