garrytan/gstack · error · Error

pdf: --format is mutex with --width/--height

Error message

pdf: --format is mutex with --width/--height

What it means

Thrown by parsePdfArgs() when both --format (named page size like 'A4' or 'Letter') and --width or --height (explicit dimensions) are specified. These are mutually exclusive ways to set page size — format is a preset, while width/height are custom values.

Source

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

    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)');
  }

  return result;
}

export function parsePdfFromFile(payloadPath: string): ParsedPdfArgs {
  // Parity with load-html --from-file (browse/src/write-commands.ts) and
  // the direct load-html <file> path: every caller-supplied file path
  // must pass validateReadPath so the safe-dirs policy can't be skirted
  // by routing reads through the --from-file shortcut.
  try {
    validateReadPath(path.resolve(payloadPath));
  } catch {
    throw new Error(
      `pdf: --from-file ${payloadPath} must be under ${SAFE_DIRECTORIES.join(' or ')} (security policy). Copy the payload into the project tree or /tmp first.`

View on GitHub (pinned to 94993f7401)

Solutions

1. Use only --format for standard paper sizes (A4, Letter, Legal, etc.)
2. Use only --width and --height together for custom page dimensions
3. Remove whichever group you do not need

Example fix

# before
$B pdf --format A4 --width 8.5in --height 11in page.pdf

# after — standard
$B pdf --format A4 page.pdf
# OR custom
$B pdf --width 8.5in --height 11in page.pdf

const hasFormat = args.includes('--format');
const hasDimensions = args.includes('--width') || args.includes('--height');
if (hasFormat && hasDimensions) {
  throw new Error('Cannot combine --format with --width/--height');
}

When it happens

Trigger: Passing --format together with --width and/or --height in the same command.

Common situations: User copies a format flag from one example and dimension flags from another, or tries to override one dimension of a named format.

Related errors

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

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