{"record":{"id":"bbeaf4da21f0fac7","repo":"ocrmypdf/OCRmyPDF","slug":"sidecar-filename-needed-when-output-file-is-stdo","errorCode":null,"errorMessage":"--sidecar filename needed when output file is stdout.","messagePattern":"--sidecar filename needed when output file is stdout\\.","errorType":"validation","errorClass":"BadArgsError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/_validation.py","lineNumber":92,"sourceCode":"            \"requested languages: \\n\"\n            f\"{lang_text}\\n\"\n            \"Please install the appropriate language data for your OCR engine.\\n\"\n            \"\\n\"\n            \"See the online documentation for instructions:\\n\"\n            \"    https://ocrmypdf.readthedocs.io/en/latest/languages.html\\n\"\n            \"\\n\"\n            \"Note: most languages are identified by a 3-letter ISO 639-2 Code.\\n\"\n            \"For example, English is 'eng', German is 'deu', and Spanish is 'spa'.\\n\"\n            \"Simplified Chinese is 'chi_sim' and Traditional Chinese is 'chi_tra'.\"\n            \"\\n\"\n        )\n        raise MissingDependencyError(msg)\n\n\ndef check_options_sidecar(options: OcrOptions) -> None:\n    if options.sidecar == '\\0':\n        if options.output_file == '-':\n            raise BadArgsError(\"--sidecar filename needed when output file is stdout.\")\n        elif options.output_file == os.devnull:\n            raise BadArgsError(\n                \"--sidecar filename needed when output file is /dev/null or NUL.\"\n            )\n        elif not isinstance(options.output_file, str | Path):\n            # The '\\0' sentinel is only ever set by the CLI, which always\n            # supplies output_file as a plain path - not a stream. If this\n            # somehow fires, the caller mixed a CLI-only sentinel with the\n            # stream-based API.\n            raise BadArgsError(\n                \"--sidecar filename needed when output file is not a path.\"\n            )\n        options.sidecar = os.fspath(options.output_file) + '.txt'\n    if options.sidecar == options.input_file or options.sidecar == options.output_file:\n        raise BadArgsError(\n            \"--sidecar file must be different from the input and output files\"\n        )\n","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/_validation.py#L74-L110","documentation":"Raised when --sidecar was requested without a filename while the output file is stdout ('-'). Since the text sidecar cannot be inferred from a stream, an explicit filename is required.","triggerScenarios":"options.sidecar == '\\0' sentinel (CLI --sidecar with no argument) and options.output_file == '-'; checked in check_options_sidecar.","commonSituations":"Piping ocrmypdf output to another command (ocrmypdf ... - | ...) while also wanting a text sidecar.","solutions":["Give --sidecar an explicit filename: --sidecar out.txt","Don't use --sidecar at all when writing the PDF to stdout"],"exampleFix":"# before\nocrmypdf --sidecar in.pdf - > out.pdf\n# after\nocrmypdf --sidecar out.txt in.pdf - > out.pdf","handlingStrategy":"validation","validationCode":"if sidecar is None and str(output_file) == '-':\n    sidecar = default_path.with_suffix('.txt')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When piping to stdout, always pair --sidecar with an explicit filename"],"tags":["ocr","ocrmypdf","sidecar","stdout","cli-arguments"],"backgroundTag":"invalid-option-combination","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}