#3170·mdBook

`optional = true` renderer fails with Broken pipe mdBook 0.5.4

Author: cusmaCreated Jul 30, 2026Updated Aug 10, 2026
LabelsC-bug

Problem

On Linux, mdBook 0.5.4 fails when a configured renderer is not installed, even when the renderer is marked as optional.

The same setup worked with mdBook 0.5.1 and started failing after upgrading to 0.5.4.

According to the documentation, optional = true should demote a missing renderer error to a warning:

https://rust-lang.github.io/mdBook/format/configuration/renderers.html#optional-backends

Actual behavior

INFO Book building has started
INFO Running the html backend
INFO HTML book written to `/book/book/html`
INFO Running the missing backend
INFO Invoking the "missing" renderer
WARN Error writing the RenderContext to the backend, Broken pipe (os error 32)
ERROR Renderer exited with non-zero return code.
ERROR Rendering failed
      Caused by: The "missing" renderer failed

mdBook exits with code 101.

Expected behavior

mdBook should emit a warning that mdbook-missing was not found, skip the optional renderer, and complete the HTML build successfully.

For example:

WARN The command `mdbook-missing` for backend `missing` was not found, but is marked as optional.

Steps

Create a book with this configuration:

[book]
title = "Optional renderer reproduction"
src = "src"

[output.html]

[output.missing]
optional = true

With a minimal src/SUMMARY.md and chapter, ensure mdbook-missing is not installed, then run:

mdbook build

The same failure occurs during the initial build performed by:

mdbook serve

Possible Solution(s)

No response

Notes

Failing environment:

mdbook v0.5.4
rustc 1.97.1
Linux x86_64
Debian trixie container
Installed with: cargo install --locked mdbook --version 0.5.4

For comparison, the same mdBook version and configuration on Darwin arm64 correctly detects that the executable is missing, emits the optional-renderer warning, and exits successfully.

Version

mdbook v0.5.4