Skip to content

optional = true renderer fails with Broken pipe mdBook 0.5.4 #3170

Description

@cusma

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    C-bugCategory: A bug, incorrect or unintended behavior

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions