{"record":{"id":"1345ef01df4fa5b9","repo":"podman-container-tools/podman","slug":"error-while-processing-infile-line-line-1","errorCode":null,"errorMessage":"Error while processing {infile} line '{line[:-1]}'","messagePattern":"Error while processing (.+?) line '(.+?)'","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"hack/markdown-preprocess","lineNumber":159,"sourceCode":"            for line in fh_in:\n                try:\n                    # '@@option foo' -> include file options/foo.md\n                    if line.startswith('@@option '):\n                        _, optionname = line.strip().split(\" \")\n                        is_quadlet = optionname.startswith(\"quadlet:\")\n                        if is_quadlet:\n                            optionname = optionname[len(\"quadlet:\"):]\n                        optionfile = os.path.join(\"options\", optionname + '.md')\n                        self.track_optionfile(optionfile)\n                        self.insert_file(fh_out, optionfile, is_quadlet)\n                    # '@@include relative-path/must-exist.md'\n                    elif line.startswith('@@include '):\n                        _, path = line.strip().split(\" \")\n                        self.insert_file(fh_out, path)\n                    else:\n                        fh_out.write(line)\n                except Exception as ex:\n                    raise Exception(f\"Error while processing {infile} line '{line[:-1]}'\") from ex\n\n        os.chmod(outfile_tmp, 0o444)\n        os.rename(outfile_tmp, outfile)\n\n    def track_optionfile(self, optionfile: str):\n        \"\"\"\n        Keep track of which man pages use which option files\n        \"\"\"\n        if optionfile not in self.used_by:\n            self.used_by[optionfile] = []\n        self.used_by[optionfile].append(self.podman_subcommand('full'))\n\n    def rewrite_optionfiles(self):\n        \"\"\"\n        Rewrite all option files, such that they include header comments\n        cross-referencing all the man pages in which they're used.\n        \"\"\"\n        for optionfile in self.used_by:","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/podman-container-tools/podman/blob/a2409076ef2fef60ad9ac046375dedc7d9410ef4/hack/markdown-preprocess#L141-L177","documentation":"Umbrella error from Preprocessor.process(): any exception raised while handling one line of a *.md.in file is re-raised with the file name and offending line text, original error chained in __cause__. The lines it wraps are '@@option NAME' (insert_file of options/NAME.md, optionally with quadlet: prefix) and '@@include PATH' — so typical causes are FileNotFoundError for a missing option/include file, ValueError from split(' ') when the line has extra spaces/fields, or any render()/replace_type error (undefined variable, bad pod|container token) bubbling up from the included file.","triggerScenarios":"'@@option rm' when options/rm.md does not exist; '@@include foo bar.md' (space in path breaks the two-field split); '@@option quadlet:containers.pod' where options/containers.pod.md is missing; a render/replace_type error inside the included option file (errors 0-5, 7, 8 surface wrapped as this message).","commonSituations":"Renaming or deleting an option file without updating @@option references; typos in option names; adding new @@option lines for options whose .md was never created; paths with spaces or tabs; merge conflicts leaving duplicated @@option lines.","solutions":["Read the chained exception (ex.__cause__ or the traceback's 'The above exception was the direct cause') to get the real error","Verify the referenced file exists: ls docs/source/markdown/options/NAME.md (for quadlet, the file name after the 'quadlet:' prefix)","Fix the directive syntax: exactly one space, two fields ('@@option NAME' / '@@include PATH')","If the cause is a render/replace_type error, fix the option file per that error's guidance"],"exampleFix":"# before (docs/source/markdown/podman-pod-run.1.md.in)\n@@option pod-create-sigstore\n\n# after (name must match options/pod-create-sigstore.md if that file exists; else use the real file)\n@@option pod-create","handlingStrategy":"try-catch","validationCode":"# Verify every @@option/@@include target exists before running\nimport pathlib, re, sys\nmd = pathlib.Path('docs/source/markdown')\nmissing = []\nfor f in md.glob('*.md.in'):\n    for line in f.read_text().splitlines():\n        if line.startswith('@@option ') or line.startswith('@@include '):\n            parts = line.strip().split(' ')\n            if len(parts) != 2:\n                missing.append(f'{f.name}: bad directive {line!r} (expected exactly 2 fields)')\n                continue\n            target = parts[1].removeprefix('quadlet:')\n            path = md / 'options' / (target + '.md') if line.startswith('@@option ') else md / target\n            if not path.is_file():\n                missing.append(f'{f.name}: {line.strip()} -> missing {path.relative_to(md)}')\nif missing:\n    sys.exit('\\n'.join(missing))","typeGuard":null,"tryCatchPattern":"try:\n    preprocessor.process(infile)\nexcept Exception as ex:\n    cause = ex.__cause__  # the real error: FileNotFoundError, ValueError from split, render/replace_type errors\n    raise SystemExit(f'{ex}\\n  caused by: {type(cause).__name__}: {cause}') from None","preventionTips":["Always inspect the chained exception (__cause__) — this wrapper is only a locator; the real failure is underneath","Add new option files in the same commit that adds the @@option reference, and name the file exactly as referenced (plus .md)","Keep @@option/@@include lines to exactly one space and two fields; quote nothing (paths with spaces are unsupported)"],"tags":["markdown","docs","includes","build"],"backgroundTag":null,"analyzedSha":"a2409076ef2fef60ad9ac046375dedc7d9410ef4","analyzedAt":"2026-08-15T15:57:05.625Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}