rust-lang / rust-lang/mdBook

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

Open
#3,170 1 comment 0 reactions 1 assignee View on GitHub

@tianrking is already working on this.

Since Aug 10, 2026.

C-bug
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.