{"record":{"id":"2e26868464d49769","repo":"garrytan/gstack","slug":"pdf-page-numbers-is-mutex-with-footer-templat","errorCode":null,"errorMessage":"pdf: --page-numbers is mutex with --footer-template (page-numbers writes the footer itself)","messagePattern":"pdf: --page-numbers is mutex with --footer-template \\(page-numbers writes the footer itself\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":134,"sourceCode":"    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.`\n    );\n  }\n  const raw = fs.readFileSync(payloadPath, 'utf8');","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L116-L152","documentation":"Thrown by parsePdfArgs() when both --page-numbers and --footer-template are specified. The --page-numbers flag auto-generates a page-number footer, so it inherently writes the footer slot and conflicts with any custom --footer-template.","triggerScenarios":"Passing both --page-numbers and --footer-template in the same command.","commonSituations":"User wants page numbers and also a custom footer, not realizing --page-numbers writes its own footer template internally.","solutions":["Use only --page-numbers for automatic page numbering","Use only --footer-template and include page-number placeholders (e.g., <span class='pageNumber'></span>) in the custom template for combined needs","Remove one of the conflicting flags"],"exampleFix":"# before\n$B pdf --page-numbers --footer-template '<div>Footer</div>' page.pdf\n\n# after — custom footer with page numbers built in\n$B pdf --footer-template '<div>Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>' page.pdf","handlingStrategy":"validation","validationCode":"const hasPageNumbers = args.includes('--page-numbers');\nconst hasFooterTemplate = args.includes('--footer-template');\nif (hasPageNumbers && hasFooterTemplate) {\n  throw new Error('Cannot combine --page-numbers with --footer-template');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use --page-numbers for simple automatic numbering","Use --footer-template with pageNumber/totalPages spans if you need both custom content and page numbers","Never pass both flags in the same 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"}