{"record":{"id":"f51e644f2a61ac10","repo":"garrytan/gstack","slug":"pdf-margins-is-mutex-with-margin-top-margin","errorCode":null,"errorMessage":"pdf: --margins is mutex with --margin-top/--margin-right/--margin-bottom/--margin-left","messagePattern":"pdf: --margins is mutex with --margin-top/--margin-right/--margin-bottom/--margin-left","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":125,"sourceCode":"    else if (a === '--margin-bottom') { result.marginBottom = requireValue(args, ++i, 'margin-bottom'); }\n    else if (a === '--margin-left') { result.marginLeft = requireValue(args, ++i, 'margin-left'); }\n    else if (a === '--header-template') { result.headerTemplate = requireValue(args, ++i, 'header-template'); }\n    else if (a === '--footer-template') { result.footerTemplate = requireValue(args, ++i, 'footer-template'); }\n    else if (a === '--page-numbers') { result.pageNumbers = true; }\n    else if (a === '--tagged') { result.tagged = true; }\n    else if (a === '--outline') { result.outline = true; }\n    else if (a === '--print-background') { result.printBackground = true; }\n    else if (a === '--prefer-css-page-size') { result.preferCSSPageSize = true; }\n    else if (a === '--toc') { result.toc = true; }\n    else if (a.startsWith('--')) { throw new Error(`Unknown pdf flag: ${a}`); }\n    else { positional.push(a); }\n  }\n\n  if (positional.length > 0) result.output = positional[0];\n\n  if (margins !== undefined) {\n    if (result.marginTop || result.marginRight || result.marginBottom || result.marginLeft) {\n      throw new Error('pdf: --margins is mutex with --margin-top/--margin-right/--margin-bottom/--margin-left');\n    }\n    result.marginTop = result.marginRight = result.marginBottom = result.marginLeft = margins;\n  }\n\n  if (result.format && (result.width || result.height)) {\n    throw new Error('pdf: --format is mutex with --width/--height');\n  }\n  if (result.pageNumbers && result.footerTemplate) {\n    throw new Error('pdf: --page-numbers is mutex with --footer-template (page-numbers writes the footer itself)');\n  }\n\n  return result;\n}\n\nexport function parsePdfFromFile(payloadPath: string): ParsedPdfArgs {\n  // Parity with load-html --from-file (browse/src/write-commands.ts) and\n  // the direct load-html <file> path: every caller-supplied file path\n  // must pass validateReadPath so the safe-dirs policy can't be skirted","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L107-L143","documentation":"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.","triggerScenarios":"Passing both --margins and at least one of --margin-top/--margin-right/--margin-bottom/--margin-left in the same command.","commonSituations":"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.","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"],"exampleFix":"# before\n$B pdf --margins 1in --margin-top 2in page.pdf\n\n# after — uniform\n$B pdf --margins 1in page.pdf\n# OR per-side\n$B pdf --margin-top 2in --margin-right 1in --margin-bottom 1in --margin-left 1in page.pdf","handlingStrategy":"validation","validationCode":"const hasMargins = args.includes('--margins');\nconst hasIndividual = args.some(a => a.startsWith('--margin-') && a !== '--margins');\nif (hasMargins && hasIndividual) {\n  throw new Error('Cannot combine --margins with individual margin flags');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Choose one margin specification strategy: uniform (--margins) or per-side (individual flags)","Validate mutex constraints before building the command"],"tags":["pdf","cli","mutex"],"backgroundTag":null,"analyzedSha":"94993f74012782fd94416dd44b8314f6363a13a4","analyzedAt":"2026-08-12T04:06:23.140Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}