garrytan/gstack · error · Error

pdf: --from-file requires a path

Error message

pdf: --from-file requires a path

What it means

Thrown by parsePdfArgs() when the --from-file flag is present but is the last token in argv — the (++i) increment reads undefined. The --from-file flag short-circuits all other argv parsing and delegates to parsePdfFromFile, so it must be followed by a file path.

Source

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

  marginRight?: string;
  marginBottom?: string;
  marginLeft?: string;
  headerTemplate?: string;
  footerTemplate?: string;
  pageNumbers?: boolean;
  tagged?: boolean;
  outline?: boolean;
  printBackground?: boolean;
  preferCSSPageSize?: boolean;
  toc?: boolean;
}

function parsePdfArgs(args: string[]): ParsedPdfArgs {
  // --from-file short-circuits argv parsing entirely
  for (let i = 0; i < args.length; i++) {
    if (args[i] === '--from-file') {
      const payloadPath = args[++i];
      if (!payloadPath) throw new Error('pdf: --from-file requires a path');
      return parsePdfFromFile(payloadPath);
    }
  }

  const result: ParsedPdfArgs = {
    output: `${TEMP_DIR}/browse-page.pdf`,
  };

  let margins: string | undefined;
  const positional: string[] = [];

  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a === '--format') { result.format = requireValue(args, ++i, 'format'); }
    else if (a === '--page-size') { result.format = requireValue(args, ++i, 'page-size'); }
    else if (a === '--width') { result.width = requireValue(args, ++i, 'width'); }
    else if (a === '--height') { result.height = requireValue(args, ++i, 'height'); }
    else if (a === '--margins') { margins = requireValue(args, ++i, 'margins'); }

View on GitHub (pinned to 94993f7401)

Solutions

1. Add the JSON file path immediately after --from-file
2. If building the command programmatically, ensure the path variable is non-empty before appending it

Example fix

# before
$B pdf --from-file

# after
$B pdf --from-file /tmp/pdf-config.json

// Validate --from-file has a path before invoking
const idx = args.indexOf('--from-file');
if (idx !== -1 && idx === args.length - 1) {
  throw new Error('--from-file requires a path argument');
}

// Wrap CLI invocation in try-catch for user-facing error display
try {
  await runPdfCommand(args);
} catch (e) {
  if (e.message.includes('--from-file requires a path')) {
    showUsage('pdf --from-file <path>');
  }
}

When it happens

Trigger: Passing '--from-file' as the final argument to the pdf command with no subsequent path token.

Common situations: User forgets to specify the JSON payload path after --from-file, or a script constructs the command string and omits the path argument.

Related errors

• Unknown pdf flag: ${a}
• pdf: --${flag} requires a value
• pdf: --margins is mutex with --margin-top/--margin-right/--m
• pdf: --format is mutex with --width/--height
• pdf: --page-numbers is mutex with --footer-template (page-nu

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