heygen-com/hyperframes · error · Error

Unknown context field${invalid.length === 1 ? "" : "s"}: ${i

Error message

Unknown context field${invalid.length === 1 ? "" : "s"}: ${invalid.join(", ")}

What it means

Thrown by parseContextFields when one or more comma-separated values in --context-fields are not in the allowed set {server, selection, lint, capabilities}. The invalid entries are echoed back along with the count-aware 'field/fields' phrasing so the user knows exactly what to correct.

Source

Thrown at packages/cli/src/commands/preview.ts:491

  return {
    port: server.port,
    projectName: server.projectName,
    projectDir: server.projectDir,
    url: previewBaseUrl(server.port, server.host),
  };
}

function parseContextFields(value: string | undefined): ContextField[] {
  if (value === undefined) return DEFAULT_CONTEXT_FIELDS;
  if (!value.trim()) throw new Error("--context-fields cannot be empty");
  const allowed = new Set<ContextField>(DEFAULT_CONTEXT_FIELDS);
  const fields = value
    .split(",")
    .map((field) => field.trim())
    .filter(Boolean);
  const invalid = fields.filter((field) => !allowed.has(field as ContextField));
  if (invalid.length > 0) {
    throw new Error(
      `Unknown context field${invalid.length === 1 ? "" : "s"}: ${invalid.join(", ")}`,
    );
  }
  return [...new Set(fields)] as ContextField[];
}

function contextIncludes(fields: ContextField[], field: ContextField): boolean {
  return fields.includes(field);
}

function addContextError(
  payload: Record<string, unknown>,
  field: ContextField,
  error: { code: string; message: string },
): void {
  payload.errors = {
    ...((payload.errors as Record<string, unknown> | undefined) ?? {}),
    [field]: error,

View on GitHub (pinned to c2996c8626)

Solutions

1. Use only valid fields: `--context-fields server,selection,lint,capabilities`
2. Check the allowed set in packages/cli/src/commands/preview.ts:110 for your CLI version
3. Upgrade the CLI if you expected a field that exists in newer docs

Example fix

// before
hyperframes preview --context-fields server,foo
// after
hyperframes preview --context-fields server,lint

const ALLOWED = new Set(["server", "selection", "lint", "capabilities"]);
function validContextFields(v: string): string[] {
  const fields = v.split(",").map((s) => s.trim()).filter(Boolean);
  const bad = fields.filter((f) => !ALLOWED.has(f));
  if (bad.length) throw new Error(`Invalid context fields: ${bad.join(", ")}`);
  return fields;
}

function isContextField(v: string): v is "server" | "selection" | "lint" | "capabilities" {
  return v === "server" || v === "selection" || v === "lint" || v === "capabilities";
}

When it happens

Trigger: Calling `hyperframes preview --context-fields foo` or `--context-fields server,foobar`. Each split+trimmed token is checked against the Set built from DEFAULT_CONTEXT_FIELDS; any token not present lands in `invalid` and triggers the throw at preview.ts:491.

Common situations: Typos (e.g. 'capabilties'), stale field names from an older CLI version, copying a field list from docs for a different release, or an agent guessing field names.

Related errors

• --context-fields cannot be empty
• Unknown skill(s): ${unknown.join(", ")}. Available: ${[...ma
• --source must be 'sparticuz' or 'chrome-headless-shell' (got
• Unknown flag: ${arg}
• --executable-path requires a path

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