garrytan/gstack · error · Error

Unknown pdf flag: ${a}

Error message

Unknown pdf flag: ${a}

What it means

Thrown by parsePdfArgs() when a token starts with '--' but does not match any recognized PDF flag. The parser checks against a fixed set of known flags (--margin-top, --format, --width, etc.) and falls through to this error for any unrecognized double-dash token.

Source

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

    const a = args[i];
    if (a === '--format') { result.format = requireValue(args, ++i, 'format'); }
    else if (a === '--page-size') { result.format = requireValue(args, ++i, 'page-size'); }
    else if (a === '--width') { result.width = requireValue(args, ++i, 'width'); }
    else if (a === '--height') { result.height = requireValue(args, ++i, 'height'); }
    else if (a === '--margins') { margins = requireValue(args, ++i, 'margins'); }
    else if (a === '--margin-top') { result.marginTop = requireValue(args, ++i, 'margin-top'); }
    else if (a === '--margin-right') { result.marginRight = requireValue(args, ++i, 'margin-right'); }
    else if (a === '--margin-bottom') { result.marginBottom = requireValue(args, ++i, 'margin-bottom'); }
    else if (a === '--margin-left') { result.marginLeft = requireValue(args, ++i, 'margin-left'); }
    else if (a === '--header-template') { result.headerTemplate = requireValue(args, ++i, 'header-template'); }
    else if (a === '--footer-template') { result.footerTemplate = requireValue(args, ++i, 'footer-template'); }
    else if (a === '--page-numbers') { result.pageNumbers = true; }
    else if (a === '--tagged') { result.tagged = true; }
    else if (a === '--outline') { result.outline = true; }
    else if (a === '--print-background') { result.printBackground = true; }
    else if (a === '--prefer-css-page-size') { result.preferCSSPageSize = true; }
    else if (a === '--toc') { result.toc = true; }
    else if (a.startsWith('--')) { throw new Error(`Unknown pdf flag: ${a}`); }
    else { positional.push(a); }
  }

  if (positional.length > 0) result.output = positional[0];

  if (margins !== undefined) {
    if (result.marginTop || result.marginRight || result.marginBottom || result.marginLeft) {
      throw new Error('pdf: --margins is mutex with --margin-top/--margin-right/--margin-bottom/--margin-left');
    }
    result.marginTop = result.marginRight = result.marginBottom = result.marginLeft = margins;
  }

  if (result.format && (result.width || result.height)) {
    throw new Error('pdf: --format is mutex with --width/--height');
  }
  if (result.pageNumbers && result.footerTemplate) {
    throw new Error('pdf: --page-numbers is mutex with --footer-template (page-numbers writes the footer itself)');
  }

View on GitHub (pinned to 94993f7401)

Solutions

  1. Check the flag spelling against the known set: --output, --format, --width, --height, --margins, --margin-top/right/bottom/left, --header-template, --footer-template, --page-numbers, --tagged, --outline, --print-background, --prefer-css-page-size, --toc
  2. If the flag is valid in a different version, check for version mismatches
  3. Remove the unrecognized flag or replace it with the correct equivalent

Example fix

# before
$B pdf --formatt A4 page.pdf

# after
$B pdf --format A4 page.pdf
Defensive patterns

Strategy: validation

Validate before calling

const KNOWN_PDF_FLAGS = new Set([
  '--output','--format','--width','--height','--margins',
  '--margin-top','--margin-right','--margin-bottom','--margin-left',
  '--header-template','--footer-template','--page-numbers',
  '--tagged','--outline','--print-background','--prefer-css-page-size','--toc','--from-file'
]);
for (const a of args) {
  if (a.startsWith('--') && !KNOWN_PDF_FLAGS.has(a)) {
    throw new Error(`Unknown pdf flag: ${a}`);
  }
}

Prevention

When it happens

Trigger: Passing any unrecognized '--flag' to the pdf command, e.g., '--paper-size', '--orientation', or a typo like '--formatt'.

Common situations: Typo in a flag name, using a flag from a different command, or passing a flag from a newer/older version of the API.

Related errors

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