{"record":{"id":"59363112ce2fb0bc","repo":"rust-lang/mdBook","slug":"the-preprocessor-exited-unsuccessfully-with","errorCode":null,"errorMessage":"The \"{}\" preprocessor exited unsuccessfully with {} status","messagePattern":"The \"(.+?)\" preprocessor exited unsuccessfully with (.+?) status","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/mdbook-driver/src/builtin_preprocessors/cmd.rs","lineNumber":99,"sourceCode":"                )?;\n                // This should normally not be reached, since the validation\n                // for NotFound should have already happened when running the\n                // \"supports\" command.\n                return Ok(book);\n            }\n        };\n\n        self.write_input_to_child(&mut child, &book, ctx);\n\n        let output = child.wait_with_output().with_context(|| {\n            format!(\n                \"Error waiting for the \\\"{}\\\" preprocessor to complete\",\n                self.name\n            )\n        })?;\n\n        trace!(\"{} exited with output: {:?}\", self.cmd, output);\n        ensure!(\n            output.status.success(),\n            format!(\n                \"The \\\"{}\\\" preprocessor exited unsuccessfully with {} status\",\n                self.name, output.status\n            )\n        );\n\n        serde_json::from_slice(&output.stdout).with_context(|| {\n            format!(\n                \"Unable to parse the preprocessed book from \\\"{}\\\" processor\",\n                self.name\n            )\n        })\n    }\n\n    fn supports_renderer(&self, renderer: &str) -> Result<bool> {\n        debug!(\n            \"Checking if the \\\"{}\\\" preprocessor supports \\\"{}\\\"\",","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/rust-lang/mdBook/blob/dc21064fc21d955a0e1f67e65e336883c3e5260b/crates/mdbook-driver/src/builtin_preprocessors/cmd.rs#L81-L117","documentation":"mdbook-driver runs a builtin preprocessor as a child process and calls `ensure!(output.status.success(), ...)` after waiting for it. When the child exits with a non-zero status, the ensure condition fails and this anyhow error is returned, embedding the preprocessor name and the exit status. It is the generic 'backend preprocessor crashed' error.","triggerScenarios":"Any preprocessor command defined in book.toml ([preprocessor.<name>].command) exits with non-zero status during mdbook build/test/serve; e.g. the command binary is a failing script, or `mdbook build` runs `links`/`index` builtin preprocessors that return an error code.","commonSituations":"A custom preprocessor script exits 1 on bad markdown; preprocessor binary missing dependencies and aborting; preprocessor killed by signal (status shows signal, e.g. 'signal: 9'); typo'd command that runs but fails.","solutions":["Run the preprocessor command standalone on a sample input to see its real error output.","Check book.toml [preprocessor.X] command for typos and correct working directory assumptions.","Fix the preprocessor so it exits 0 on success; make sure it reads/writes the (input, output) JSON files correctly.","Run `mdbook build` with `RUST_LOG=trace` to see the child's captured output (traced just before the ensure)."],"exampleFix":"# before\ndefective_preproc.py  # raises on error -> exit 1\n# after\ndefective_preproc.py || { echo \"preproc failed\" >&2; cat debug-log; }  # debug, then fix script to exit 0 on success","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match mdbook_driver::process(book).build(...) {\n    Err(e) if e.to_string().contains(\"exited unsuccessfully\") => {\n        eprintln!(\"preprocessor failed: {e:#}\"); // inspect the named preprocessor\n    }\n    Err(e) => eprintln!(\"build failed: {e:#}\"),\n    Ok(_) => {}\n}","preventionTips":["Test each preprocessor command standalone before wiring it into book.toml.","Make preprocessors exit 0 on success and log errors to stderr.","Pin/verify preprocessor binaries exist on PATH in CI.","Run builds with RUST_LOG=trace to capture preprocessor output."],"tags":["preprocessor","process-exit","child-process","mdbook"],"backgroundTag":"child-process-exit-nonzero","analyzedSha":"dc21064fc21d955a0e1f67e65e336883c3e5260b","analyzedAt":"2026-09-01T10:15:12.134Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}