heygen-com/hyperframes · error

--remote-debugging-port must be an integer between 1 and 655

Error message

--remote-debugging-port must be an integer between 1 and 65535

What it means

parseRemoteDebuggingPort rejects the raw string value because it fails the /^\d+$/ regex — i.e. it contains non-digit characters: a negative sign, decimal point, hex, letters, spaces, or a +. The function expects a pure digit string representing an integer port. This is the format-validation branch (the range branch at line 24 is a separate error).

Source

Thrown at packages/cli/src/utils/openBrowser.ts:20

export interface OpenBrowserOptions {
  browserPath?: string;
  userDataDir?: string;
  remoteDebuggingPort?: number;
  /**
   * Launch the browser with --disable-gpu. For hosts where hardware
   * acceleration crashes the graphics driver (wild report: auto-opened
   * preview triggered NVIDIA Xid 32 resets on NixOS). Only effective with
   * `browserPath` — the `open`-package fallback launches the system default
   * browser with no way to pass Chromium flags.
   */
  disableGpu?: boolean;
}

export function parseRemoteDebuggingPort(value: string | undefined): number | undefined {
  if (value === undefined || value === "") return undefined;
  if (!/^\d+$/.test(value)) {
    throw new Error("--remote-debugging-port must be an integer between 1 and 65535");
  }
  const port = Number(value);
  if (port < 1 || port > 65535) {
    throw new Error("--remote-debugging-port must be an integer between 1 and 65535");
  }
  return port;
}

export interface RemoteDebuggingPortDeps {
  browserPath?: string;
  userDataDir?: string;
  remoteDebuggingPort?: string;
}

/**
 * Returns an error message if --remote-debugging-port is set without its required
 * dependencies (--browser-path and --user-data-dir), or null if everything is OK.
 */

View on GitHub (pinned to c2996c8626)

Solutions

1. Pass a plain positive integer string, e.g. --remote-debugging-port=9222.
2. Strip any non-digit characters from the value before passing it in.
3. If the value comes from a config, ensure the config serializes it as an integer, not a hex/float.

Example fix

# before
hyperframes preview --remote-debugging-port=0x23f3
# after
hyperframes preview --remote-debugging-port=9222

function isValidPortInput(v: unknown): v is string {
  return typeof v === 'string' && /^\d+$/.test(v);
}

const raw = config.remoteDebuggingPort;
if (raw !== undefined && raw !== '' && !isValidPortInput(raw)) {
  throw new Error('remoteDebuggingPort must be a digit-only string');
}

function isDigitOnlyPortString(v: unknown): v is string {
  return typeof v === 'string' && /^\d+$/.test(v) && Number(v) >= 1 && Number(v) <= 65535;
}

try {
  const port = parseRemoteDebuggingPort(rawValue);
} catch (err) {
  if (err instanceof Error && /must be an integer/.test(err.message)) {
    console.error('Pass --remote-debugging-port as a plain integer (e.g. 9222).');
  } else throw err;
}

When it happens

Trigger: Passing --remote-debugging-port with a non-integer value: '9222abc', '0x23f3', '22.5', '-1', '9222 ' (trailing space), 'port', or an empty-ish non-string. The value is a string from the CLI/argv before it reaches this parser.

Common situations: User typed a hex port; a shell variable expanded with extra characters; a copy-paste from a URL like chrome://inspect?port=9222 that carried extra chars; a config file providing a YAML number that got coerced oddly.

Related errors

• LUT for "${cell.label}" is not a valid .cube: ${normalizeErr
• 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/a423640465dc3989. Report an issue: GitHub.