{"record":{"id":"74d5c7fc2d8375b3","repo":"garrytan/gstack","slug":"pdf-flag-requires-a-value","errorCode":null,"errorMessage":"pdf: --${flag} requires a value","messagePattern":"pdf: --(.+?) requires a value","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":187,"sourceCode":"    marginRight: json.marginRight,\n    marginBottom: json.marginBottom,\n    marginLeft: json.marginLeft,\n    headerTemplate: json.headerTemplate,\n    footerTemplate: json.footerTemplate,\n    pageNumbers: json.pageNumbers === true,\n    tagged: json.tagged === true,\n    outline: json.outline === true,\n    printBackground: json.printBackground === true,\n    preferCSSPageSize: json.preferCSSPageSize === true,\n    toc: json.toc === true,\n  };\n  return out;\n}\n\nfunction requireValue(args: string[], i: number, flag: string): string {\n  const v = args[i];\n  if (v === undefined || v.startsWith('--')) {\n    throw new Error(`pdf: --${flag} requires a value`);\n  }\n  return v;\n}\n\nfunction buildPdfOptions(parsed: ParsedPdfArgs): Record<string, unknown> {\n  const opts: Record<string, unknown> = {};\n\n  // Page size\n  if (parsed.format) {\n    opts.format = parsed.format.charAt(0).toUpperCase() + parsed.format.slice(1).toLowerCase();\n  } else if (parsed.width && parsed.height) {\n    opts.width = parsed.width;\n    opts.height = parsed.height;\n  } else {\n    opts.format = 'Letter';\n  }\n\n  // Margins","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L169-L205","documentation":"Thrown by requireValue() when a value-taking flag (e.g., --margin-top, --format, --width) either is the last token in argv or is immediately followed by another token starting with '--'. The parser treats any subsequent '--' token as a new flag rather than a value, so the flag is left without its required argument.","triggerScenarios":"Passing a value flag as the last argument (e.g., 'pdf --format'), or followed by another flag (e.g., 'pdf --format --page-numbers').","commonSituations":"User forgets the value, or a script concatenates flag lists without inserting the values. Also occurs when a value legitimately starts with '--' (rare for PDF args).","solutions":["Provide the value immediately after the flag, before any subsequent flags","If building the command programmatically, ensure no value slot is empty or undefined","Check that the value does not start with '--' — if it must, consider using --from-file with a JSON payload instead"],"exampleFix":"# before\n$B pdf --format --page-numbers page.pdf\n\n# after\n$B pdf --format A4 --page-numbers page.pdf","handlingStrategy":"validation","validationCode":"// Validate that value-flags have a non-flag value following them\nconst VALUE_FLAGS = ['--margin-top','--margin-right','--margin-bottom','--margin-left','--header-template','--footer-template','--format','--width','--height','--margins'];\nfor (let i = 0; i < args.length; i++) {\n  if (VALUE_FLAGS.includes(args[i])) {\n    const next = args[i + 1];\n    if (!next || next.startsWith('--')) {\n      throw new Error(`${args[i]} requires a value`);\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When building commands programmatically, assert each value flag is immediately followed by a non-flag token","Use --from-file with a JSON payload to avoid argv ordering issues entirely"],"tags":["pdf","cli","argument-parsing"],"backgroundTag":null,"analyzedSha":"94993f74012782fd94416dd44b8314f6363a13a4","analyzedAt":"2026-08-12T04:06:23.140Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}