{"record":{"id":"4c9770a5b082fe65","repo":"garrytan/gstack","slug":"pdf-format-is-mutex-with-width-height","errorCode":null,"errorMessage":"pdf: --format is mutex with --width/--height","messagePattern":"pdf: --format is mutex with --width/--height","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":131,"sourceCode":"    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\n  // by routing reads through the --from-file shortcut.\n  try {\n    validateReadPath(path.resolve(payloadPath));\n  } catch {\n    throw new Error(\n      `pdf: --from-file ${payloadPath} must be under ${SAFE_DIRECTORIES.join(' or ')} (security policy). Copy the payload into the project tree or /tmp first.`","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L113-L149","documentation":"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.","triggerScenarios":"Passing --format together with --width and/or --height in the same command.","commonSituations":"User copies a format flag from one example and dimension flags from another, or tries to override one dimension of a named format.","solutions":["Use only --format for standard paper sizes (A4, Letter, Legal, etc.)","Use only --width and --height together for custom page dimensions","Remove whichever group you do not need"],"exampleFix":"# before\n$B pdf --format A4 --width 8.5in --height 11in page.pdf\n\n# after — standard\n$B pdf --format A4 page.pdf\n# OR custom\n$B pdf --width 8.5in --height 11in page.pdf","handlingStrategy":"validation","validationCode":"const hasFormat = args.includes('--format');\nconst hasDimensions = args.includes('--width') || args.includes('--height');\nif (hasFormat && hasDimensions) {\n  throw new Error('Cannot combine --format with --width/--height');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Decide between named format (A4, Letter) or custom dimensions before constructing the command","Validate mutex constraints before invoking the pdf 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"}