garrytan/gstack · error · Error

pdf: --margins is mutex with --margin-top/--margin-right/--m

Error message

pdf: --margins is mutex with --margin-top/--margin-right/--margin-bottom/--margin-left

What it means

Thrown by parsePdfArgs() when --margins (which sets all four sides uniformly) is combined with any individual margin flag (--margin-top, --margin-right, --margin-bottom, or --margin-left). These are mutually exclusive because --margins overwrites all four values, making individual overrides ambiguous.

Source

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

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

  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

View on GitHub (pinned to 94993f7401)

Solutions

Use only --margins for uniform margins on all four sides
Use only the individual --margin-top/right/bottom/left flags for per-side control
Remove one of the conflicting groups

Example fix

# before
$B pdf --margins 1in --margin-top 2in page.pdf

# after — uniform
$B pdf --margins 1in page.pdf
# OR per-side
$B pdf --margin-top 2in --margin-right 1in --margin-bottom 1in --margin-left 1in page.pdf

Defensive patterns

Strategy: validation

Validate before calling

const hasMargins = args.includes('--margins');
const hasIndividual = args.some(a => a.startsWith('--margin-') && a !== '--margins');
if (hasMargins && hasIndividual) {
  throw new Error('Cannot combine --margins with individual margin flags');
}

Prevention

Choose one margin specification strategy: uniform (--margins) or per-side (individual flags)
Validate mutex constraints before building the command

When it happens

Trigger: Passing both --margins and at least one of --margin-top/--margin-right/--margin-bottom/--margin-left in the same command.

Common situations: User sets a uniform margin with --margins then tries to override one side individually, or copies flags from two different examples without realizing they conflict.

Related errors

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