garrytan/gstack · error · Error

pdf: --page-numbers is mutex with --footer-template (page-nu

Error message

pdf: --page-numbers is mutex with --footer-template (page-numbers writes the footer itself)

What it means

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.

Source

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

    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.`
    );
  }
  const raw = fs.readFileSync(payloadPath, 'utf8');

View on GitHub (pinned to 94993f7401)

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

Example fix

# before
$B pdf --page-numbers --footer-template '<div>Footer</div>' page.pdf

# after — custom footer with page numbers built in
$B pdf --footer-template '<div>Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>' page.pdf

Defensive patterns

Strategy: validation

Validate before calling

const hasPageNumbers = args.includes('--page-numbers');
const hasFooterTemplate = args.includes('--footer-template');
if (hasPageNumbers && hasFooterTemplate) {
  throw new Error('Cannot combine --page-numbers with --footer-template');
}

Prevention

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

When it happens

Trigger: Passing both --page-numbers and --footer-template in the same command.

Common situations: User wants page numbers and also a custom footer, not realizing --page-numbers writes its own footer template internally.

Related errors

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