docs agent's mkdocs build failed inside docker, missing system packages

Not specified by the original author.

TL;DR

Read the build log for the missing shared library or binary, add the system package to the Dockerfile, rebuild the image, and rerun the agent's docs build. Pin the package version so the environment stays reproducible.

The exact error

mkdocs build inside docker: missing system package error

Steps

1. Read the failure Open the agent's build log and find the missing library or command error, e.g. a missing font library for PDF export. Success check: You know the exact system package that is missing.

2. Add it to the Dockerfile Install the package with the image's package manager in the Dockerfile, before the pip install layer. Success check: The Dockerfile installs the system dependency.

3. Rebuild the image Build the image fresh (no stale cache on the changed layer) and confirm the package is present. Success check: The new image contains the system package.

4. Rerun the agent build Run the agent's mkdocs build inside the new image and confirm it completes. Success check: The docs build succeeds in the container.

When to use

• Use when a docs agent's containerized MkDocs build fails on system deps.
• Use when moving a working local docs build into Docker.

When not to use

• Not for Python package errors (pip dependency problem, not system).
• Not for mkdocs config errors (those fail identically outside Docker).

Why it happens

MkDocs plugins with native extensions (PDF export, image processing) need system libraries that slim Python images omit. A build that works on the agent's host fails in the container, and the error names the missing .so or binary.

Edge cases

Pinning the system package version matters because unpinned apt installs drift between image builds. Multi-stage builds can keep the final docs image small while the build stage carries the native toolchain.

Provenance

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

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

Thread query: docs agent's mkdocs build failed inside docker, missing system packages

TL;DR: Read the build log for the missing shared library or binary, add the system package to the Dockerfile, rebuild the image, and rerun the agent's docs build. Pin the package version so the environment stays reproducible.

Not specified by the original author.

docs agent failed: timed out waiting for mkdocs build to finish

TL;DR

Give the build more time, then make the build faster: raise the agent's subprocess timeout to a multiple of the measured build time and trim the slowest plugins. Large sites with search or macro plugins can take minutes, which trips a default 60 to 120 second agent timeout. Measure first, then tune.

The error

docs agent failed: timed out waiting for mkdocs build to finish

Steps

1. Time the build yourself to get the real number:

time mkdocs build

Expected: you get a wall-clock duration to compare against the agent's timeout. If the build takes 4 minutes and the agent waits 2, you found it.

2. Find the slow part with verbose output:

mkdocs build --verbose

Expected: you can name the slowest plugin step. Usual suspects are the search index on huge sites and macro/template plugins.

3. Raise the agent's wait. Set its subprocess timeout to 2 to 3 times the measured build time, and make it wait for process exit rather than a fixed sleep.

Expected: the agent no longer kills a healthy build that just needs time.

4. Trim build cost for agent runs. Keep a second config for automation (for example mkdocs-agent.yml) that disables the slowest plugin, and run the agent against it:

mkdocs build -f mkdocs-agent.yml

Expected: build time drops measurably and the full plugin set still runs in the normal CI job.

Use this when

• the agent kills mkdocs build on timeout but the build passes when run by hand
• the site is large and the build legitimately takes several minutes
• timeouts started after adding a new plugin or a batch of new pages

Not for this skill when

• mkdocs build fails with an actual error instead of timing out
• the build hangs forever even when run by hand (that is a real hang, investigate the plugin)
• the timeout hits a different tool like docusaurus or sphinx

Variant phrasings

mkdocs build killed after timeout in CI agent

Same fix: measure, raise the timeout, trim plugins for the agent profile.

agent subprocess timeout too short for docs build

Check whether the timeout is per-command or per-session; per-command is what the build needs.

mkdocs build slow after adding plugins

Profile with --verbose before raising timeouts; sometimes one plugin is the whole problem.

Why it happens

Agent harnesses default to short subprocess timeouts built for quick commands. MkDocs builds are single-threaded and plugin-bound, so big sites legitimately need minutes. The agent mistakes a slow-but-healthy build for a stuck one and kills it.

Edge cases

• A plugin can hang on one malformed page rather than just be slow. If the same page always stalls, bisect by excluding directories until the stall disappears.
• A full or read-only filesystem in the sandbox slows builds to a crawl. Check disk space before blaming plugins.
• With --strict, warnings become failures and buffered output can look like a hang. Read the warnings first.
• Incremental rebuilds do not apply to mkdocs build; do not expect a second run to be faster.

Provenance

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

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

Thread query: docs agent failed: timed out waiting for mkdocs build to finish

TL;DR: Give the build more time, then make the build faster: raise the agent's subprocess timeout to a multiple of the measured build time and trim the slowest plugins. Large sites with search or macro plugins can take minutes, which trips a default 60 to 120 second agent timeout. Measure first, then tune.

Not specified by the original author.

Fix MkDocs "theme 'material' not found" errors

TL;DR

The Material theme is a separate pip package and it is not installed where mkdocs runs. Install mkdocs-material in the build environment (and in the requirements your hosting uses), then rebuild. The theme loads because the package mkdocs.yml names actually exists.

The error

Aborted with 1 Configuration Errors!
ERROR - Config value 'theme': The "material" theme is not installed

Steps

1. Check: pip show mkdocs-material in the environment that runs mkdocs. Expected: 'Package(s) not found', confirming it was never installed there.

2. Install it: pip install mkdocs-material. Expected: pip reports a successful install (it pulls a compatible MkDocs along).

3. Rebuild: mkdocs build. Expected: the theme loads and the site builds with no theme error.

4. If the failure is on hosted builds (Read the Docs, CI), add mkdocs-material to the requirements file that environment installs. Expected: the remote build log shows the theme installed and the error is gone.

Use this when

• mkdocs build aborts with the material theme not installed
• a fresh virtualenv or CI container builds the docs for the first time
• local builds pass but hosted builds fail

Not for this skill when

• plugin 'search' is not installed (broken MkDocs install, not a theme problem)
• the build succeeds but the site looks unstyled (theme installed; check theme customization)
• a third-party plugin reported missing (same fix shape, different package)

Variant phrasings

• mkdocs material theme not found
• mkdocs-material not installed error
• mkdocs theme material configuration error
• mkdocs build aborted theme error

Why it happens

mkdocs.yml only names the theme; MkDocs resolves that name against installed packages at startup. mkdocs-material is not bundled with MkDocs, so any fresh environment - a new virtualenv, a CI runner, a docs host - fails until the package is installed there. The local-vs-hosted split is the classic symptom: your laptop has it, the build container does not.

Edge cases

• mkdocs-material pins a compatible MkDocs range; upgrading MkDocs alone can break the pairing, so upgrade both together.
• The theme's extra features (social cards, tags) need their own optional dependencies; a bare install builds fine but those features warn.
• If two environments fight, python -m pip install mkdocs-material and python -m mkdocs build keep pip and mkdocs on the same interpreter.

Provenance

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

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

Thread query: mkdocs-material "Error: theme 'material' not found"

TL;DR: The Material theme is a separate pip package and it is not installed where mkdocs runs. Install mkdocs-material in the build environment (and in the requirements your hosting uses), then rebuild. The theme loads because the package mkdocs.yml names actually exists.