heygen-com/hyperframes · error · Error

--context-fields cannot be empty

Error message

--context-fields cannot be empty

What it means

Thrown by parseContextFields in the preview command when --context-fields is passed but resolves to an empty/whitespace string. The flag accepts a comma-separated subset of context fields (server, selection, lint, capabilities); an explicitly empty value is rejected because it signals a malformed invocation rather than 'use defaults'. Passing nothing (omitting the flag) yields the default set and never throws.

Source

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

  projectName: string;
  projectDir: string;
}): {
  port: number;
  projectName: string;
  projectDir: string;
  url: string;
} {
  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);
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Drop the flag entirely to use the defaults: `hyperframes preview`
2. Pass a valid comma-separated subset, e.g. `--context-fields server,lint`
3. If the value comes from an env var, guard it: only add the flag when $VAR is non-empty

Example fix

// before
hyperframes preview --context-fields "$CONTEXT_FIELDS"
// after (omit when empty)
hyperframes preview ${CONTEXT_FIELDS:+--context-fields "$CONTEXT_FIELDS"}

function contextFieldsArg(v: string | undefined): string | undefined {
  if (v === undefined) return undefined; // use defaults
  if (!v.trim()) return undefined;       // drop empty -> defaults
  return v;
}
// const arg = contextFieldsArg(process.env.HF_CONTEXT_FIELDS);

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

When it happens

Trigger: Invoking `hyperframes preview --context-fields ""` or `--context-fields " "` (whitespace only). value is defined but value.trim() is empty at preview.ts:483. Omitting the flag passes undefined and returns DEFAULT_CONTEXT_FIELDS instead.

Common situations: A wrapper script or agent passes --context-fields with an env var that expanded to empty; a shell quoting bug drops the value; an editor/CI template hardcodes the flag with a placeholder that was never filled.

Related errors

• Unknown context field${invalid.length === 1 ? "" : "s"}: ${i
• 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/baa372564edaca3a. Report an issue: GitHub.