garrytan/gstack · error · Error

pdf: --${flag} requires a value

Error message

pdf: --${flag} requires a value

What it means

Thrown by requireValue() when a value-taking flag (e.g., --margin-top, --format, --width) either is the last token in argv or is immediately followed by another token starting with '--'. The parser treats any subsequent '--' token as a new flag rather than a value, so the flag is left without its required argument.

Source

Thrown at browse/src/meta-commands.ts:187

    marginRight: json.marginRight,
    marginBottom: json.marginBottom,
    marginLeft: json.marginLeft,
    headerTemplate: json.headerTemplate,
    footerTemplate: json.footerTemplate,
    pageNumbers: json.pageNumbers === true,
    tagged: json.tagged === true,
    outline: json.outline === true,
    printBackground: json.printBackground === true,
    preferCSSPageSize: json.preferCSSPageSize === true,
    toc: json.toc === true,
  };
  return out;
}

function requireValue(args: string[], i: number, flag: string): string {
  const v = args[i];
  if (v === undefined || v.startsWith('--')) {
    throw new Error(`pdf: --${flag} requires a value`);
  }
  return v;
}

function buildPdfOptions(parsed: ParsedPdfArgs): Record<string, unknown> {
  const opts: Record<string, unknown> = {};

  // Page size
  if (parsed.format) {
    opts.format = parsed.format.charAt(0).toUpperCase() + parsed.format.slice(1).toLowerCase();
  } else if (parsed.width && parsed.height) {
    opts.width = parsed.width;
    opts.height = parsed.height;
  } else {
    opts.format = 'Letter';
  }

  // Margins

View on GitHub (pinned to 94993f7401)

Solutions

1. Provide the value immediately after the flag, before any subsequent flags
2. If building the command programmatically, ensure no value slot is empty or undefined
3. Check that the value does not start with '--' — if it must, consider using --from-file with a JSON payload instead

Example fix

# before
$B pdf --format --page-numbers page.pdf

# after
$B pdf --format A4 --page-numbers page.pdf

// Validate that value-flags have a non-flag value following them
const VALUE_FLAGS = ['--margin-top','--margin-right','--margin-bottom','--margin-left','--header-template','--footer-template','--format','--width','--height','--margins'];
for (let i = 0; i < args.length; i++) {
  if (VALUE_FLAGS.includes(args[i])) {
    const next = args[i + 1];
    if (!next || next.startsWith('--')) {
      throw new Error(`${args[i]} requires a value`);
    }
  }
}

When it happens

Trigger: Passing a value flag as the last argument (e.g., 'pdf --format'), or followed by another flag (e.g., 'pdf --format --page-numbers').

Common situations: User forgets the value, or a script concatenates flag lists without inserting the values. Also occurs when a value legitimately starts with '--' (rare for PDF args).

Related errors

• pdf: --from-file requires a path
• Unknown pdf flag: ${a}
• pdf: --margins is mutex with --margin-top/--margin-right/--m
• pdf: --format is mutex with --width/--height
• pdf: --page-numbers is mutex with --footer-template (page-nu

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/74d5c7fc2d8375b3. Report an issue: GitHub.