{"record":{"id":"9bdcf3f59686205f","repo":"rust-lang/mdBook","slug":"the-renderer-failed","errorCode":null,"errorMessage":"The \"{}\" renderer failed","messagePattern":"The \"(.+?)\" renderer failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/mdbook-driver/src/builtin_renderers/mod.rs","lineNumber":83,"sourceCode":"        let mut stdin = child.stdin.take().expect(\"Child has stdin\");\n        if let Err(e) = serde_json::to_writer(&mut stdin, &ctx) {\n            // Looks like the backend hung up before we could finish\n            // sending it the render context. Log the error and keep going\n            warn!(\"Error writing the RenderContext to the backend, {}\", e);\n        }\n\n        // explicitly close the `stdin` file handle\n        drop(stdin);\n\n        let status = child\n            .wait()\n            .with_context(|| \"Error waiting for the backend to complete\")?;\n\n        trace!(\"{} exited with output: {:?}\", self.cmd, status);\n\n        if !status.success() {\n            error!(\"Renderer exited with non-zero return code.\");\n            bail!(\"The \\\"{}\\\" renderer failed\", self.name);\n        } else {\n            Ok(())\n        }\n    }\n}\n","sourceCodeStart":65,"sourceCodeEnd":89,"githubUrl":"https://github.com/rust-lang/mdBook/blob/dc21064fc21d955a0e1f67e65e336883c3e5260b/crates/mdbook-driver/src/builtin_renderers/mod.rs#L65-L89","documentation":"After waiting for an external renderer (backend command) to finish, if the process exits with a non-zero status the render() call bails with this error. The renderer's own stderr/stdout is what explains the actual failure.","triggerScenarios":"The backend command (e.g. an alternate HTML renderer or a custom preprocessor-as-renderer) exits non-zero — crash, bad config passed via environment, missing templates/assets, or command not behaving as expected.","commonSituations":"Custom renderers failing due to missing output directory permissions, broken templates, or version incompatibility with the RenderContext environment variables.","solutions":["Inspect the renderer's stderr/stdout printed above this error for the root cause","Run the renderer command manually with the same environment to reproduce","Fix or update the backend command in [output.<name>] (command = ...) configuration"],"exampleFix":"// before (book.toml)\n[output.custom]\ncommand = \"python3 render.py\"\n// after (pin an interpreter that exists and test it)\n[output.custom]\ncommand = \"/usr/bin/env python3 /path/to/render.py\"","handlingStrategy":"try-catch","validationCode":"// smoke-test the renderer command before wiring it into book.toml\nlet status = std::process::Command::new(\"render.py\").arg(\"--version\").status()?;\nassert!(status.success(), \"renderer command is not runnable\");","typeGuard":null,"tryCatchPattern":"if let Err(e) = render(ctx) {\n    if e.to_string().contains(\"renderer failed\") {\n        eprintln!(\"backend exited non-zero; see its stderr above for the root cause\");\n    }\n    return Err(e);\n}","preventionTips":["Run the backend command manually with the same env to verify it works","Check the backend's logs/stderr — this error only summarizes","Keep custom renderers updated to match the mdbook RenderContext contract"],"tags":["renderer","process","external-command"],"backgroundTag":"renderer-nonzero-exit","analyzedSha":"dc21064fc21d955a0e1f67e65e336883c3e5260b","analyzedAt":"2026-09-01T10:15:12.134Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}