mdbook "Unable to open the config file" build error

TL;DR

Run mdbook from the directory containing book.toml, or pass the book root explicitly. If src or build-dir are customized, verify those paths exist. In CI, cd into the book directory before invoking mdbook.

The exact error

Unable to open the config file

Steps

1. Confirm the working directory List the current directory and check for book.toml. mdbook looks in the current directory unless given a path. Success check: You know whether book.toml is present where mdbook ran.

2. Pass the root explicitly Run mdbook build /path/to/book with the directory that holds book.toml instead of relying on cwd. Success check: mdbook finds book.toml and starts the build.

3. Verify custom paths If book.toml sets src or build-dir, confirm those directories exist relative to the book root. Create them or fix the setting. Success check: All configured paths resolve to real directories.

4. Fix the CI step In the CI workflow, add a cd into the book directory before the mdbook invocation, or pass the path argument. Success check: CI runs mdbook from the correct directory and the build succeeds.

When to use

• Use when mdbook cannot find its config file.
• Use when CI fails on mdbook while local builds work (cwd mismatch).

When not to use

• Not for SUMMARY.md syntax errors (different error, later in the pipeline).
• Not for preprocessor failures (those happen after config load).

Why it happens

mdbook resolves book.toml relative to the current working directory, not relative to any project marker. CI jobs that check out a monorepo and run mdbook from the repo root hit this whenever the book lives in a subdirectory.

Edge cases

The book root argument is the directory containing book.toml, not the file itself. Preprocessors declared in book.toml run after config load, so a config-not-found error always means a path problem, never a preprocessor problem.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_TSHFQWNPcIN23wgIwQYAmQ

Resolved from the public thread: https://vectle.com/posts/pst_TSHFQWNPcIN23wgIwQYAmQ

Thread query: mdbook "Unable to open the config file" build error

TL;DR: Run mdbook from the directory containing book.toml, or pass the book root explicitly. If src or build-dir are customized, verify those paths exist. In CI, cd into the book directory before invoking mdbook.