heygen-com/hyperframes · error · Error

Unknown media-treatment capability: ${id}

Error message

Unknown media-treatment capability: ${id}

What it means

Thrown by getMediaTreatmentCapabilityDetail() in packages/cli/src/commands/media-treatment.ts:298. The function resolves a capability id against families (grading, correction, wheels, curves, hue-curves, secondary, scopes, presets, finishing, palettes, animation, lut, overlays), individual effects, adjustments, finishing controls, presets, and palettes. If the id matches none of those registries, it throws this.

Source

Thrown at packages/cli/src/commands/media-treatment.ts:298

      description: "Seek-safe CSS properties for registered GSAP timelines.",
      properties: capabilities.animatable,
    },
    lut: {
      id,
      description: "User-owned 3D .cube LUT support.",
      contract: capabilities.lut,
    },
    overlays: {
      id,
      description: "Authored overlay blocks owned by the HyperFrames Registry.",
      discover: "hyperframes catalog",
      apply: "hyperframes add <overlay> --dir <project> --no-clipboard --json",
    },
  } as const;

  const detail = Object.hasOwn(details, id) ? Reflect.get(details, id) : undefined;
  if (detail) return detail;
  throw new Error(`Unknown media-treatment capability: ${id}`);
}

export const examples: Example[] = [
  [
    "Discover the complete treatment surface without loading every control",
    `hyperframes media-treatment --capabilities --json`,
  ],
  [
    "Inspect one relevant effect in detail",
    `hyperframes media-treatment --capability kuwahara --json`,
  ],
  [
    "Inspect the exhaustive machine-readable catalog",
    `hyperframes media-treatment --capabilities --all --json`,
  ],
  [
    "Apply a resolved treatment to one media element",
    `hyperframes media-treatment --selector '#hero' --grading '{"preset":"skin-soft","intensity":0.6}' --apply`,

View on GitHub (pinned to c2996c8626)

Solutions

1. List valid ids: `hyperframes media-treatment --capabilities --json` (overview) or `--all` (full catalog).
2. Fix the typo / casing to match a listed id.
3. Update the CLI (`bun update` / reinstall) if the id is documented for a newer version.
4. If exploring interactively, drill in with `--capability <family>` first to see child ids.

Example fix

# before
hyperframes media-treatment --capability whels --json   # typo
# after
hyperframes media-treatment --capability wheels --json

import { getMediaTreatmentCapabilityOverview } from './media-treatment.js';

function isKnownCapabilityFamily(id: string): boolean {
  const overview = getMediaTreatmentCapabilityOverview() as { families: { id: string }[] };
  return overview.families.some((f) => f.id === id);
}

try {
  getMediaTreatmentCapabilityDetail(id);
} catch (error) {
  if (/Unknown media-treatment capability/.test(String(error))) {
    // list valid ids and ask the caller to pick
    console.error('Unknown capability. Run: hyperframes media-treatment --capabilities --json');
    process.exit(1);
  }
  throw error;
}

When it happens

Trigger: Running `hyperframes media-treatment --capability <id>` where <id> is not any registered family, control, effect, preset, or palette id.

Common situations: Typo in the id; using an id introduced in a newer CLI version than is installed; copy-pasting an id from outdated docs; case mismatch (ids are lowercase kebab-case).

Related errors

• Invalid color-grading ${issue.path}: ${issue.message}.${hint
• invalid-vars
• ${source}: ${errorMessage(error)}
• --batch must be a JSON array of objects, or an object with a
• ${source} contains zero rows.

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/e73780e4d5c95a86. Report an issue: GitHub.