# Troubleshooting MkDocs Material

Read this reference when a build, preview, plugin, Markdown extension, theme
override, asset, link, or deployed site fails or behaves unexpectedly.

## Diagnostic order

1. Capture the exact command, working directory, config path, selected
   interpreter or image, complete error, and exit code.
2. Reproduce in the project's established environment. If several configs
   exist, pass the intended one explicitly with `--config-file`.
3. Establish a baseline when possible: did the same command fail before the
   requested change? Keep new failures separate from existing warnings.
4. Classify the failure as YAML/schema, dependency/plugin, content/navigation,
   Markdown extension, override/asset, or hosting/base-URL related.
5. Apply the narrowest correction, rerun the focused command, then rerun the
   complete project build.

Do not install packages, delete generated output, publish, or rewrite a whole
configuration merely to probe a failure unless that action is within the
user-approved scope.

## Symptom guide

| Symptom | First checks | Typical correction |
|---|---|---|
| YAML parser error | Reported line plus preceding indentation, tabs, duplicate/misnested keys | Repair the smallest YAML structure and validate again. |
| `Config value 'plugins'` error | Exact plugin name, active environment, dependency declarations, plugin docs | Correct the key or declare/install a compatible package with authorization. |
| Page in `nav` is missing | `docs_dir`, spelling/case, suffix, generated-page timing | Make the path relative to `docs_dir` or create the intended page. |
| Unknown Markdown extension | Active interpreter, extension name, dependency version | Use the documented extension identifier and compatible installed package. |
| Tabs render as plain text | `pymdownx.tabbed`, indentation, `alternate_style`, companion fences for nested code | Enable/configure the extension and fix page syntax; `content.tabs.link` alone is insufficient. |
| Override template not found or broken | `theme.custom_dir`, relative path, upstream template name, Material version | Fix the override path or update the minimal block override for the installed version. |
| CSS/JavaScript missing | Path under `docs_dir`, `extra_css`/`extra_javascript`, browser network errors, instant navigation lifecycle | Correct the asset declaration and reinitialize page-specific JavaScript when required. |
| Strict build aborts on warnings | First warning, normal-build output, baseline before the change | Fix regressions; report unrelated existing warnings separately instead of hiding them. |
| Links break only under a hosted subpath | `site_url`, hosting base path, absolute `/...` links, CI artifact layout | Set the real canonical subpath and use generated/internal relative links appropriately. |
| Preview works but deployed site fails | CI command, dependency versions, config selection, environment variables, case-sensitive paths | Reproduce the production build inputs and correct the differing assumption. |

## Version and environment mismatches

Dependency declarations, installed packages, the command on `PATH`, and a CI
image can all describe different versions. Capture version evidence from the
same execution path that fails. With local Python, prefer:

```powershell
python -m mkdocs --version
python -m pip show mkdocs-material
```

Use the project's interpreter in place of generic `python` when one is defined.
For containers, inspect the Dockerfile/image inputs and run version commands in
the project image if it already exists. Do not silently fall back to a global
MkDocs executable.

When current online documentation differs from the installed release, either
use the installed release's supported form or propose a separately authorized
upgrade. Label behavior that cannot be verified rather than inventing a key.

## Build warnings and strict mode

`--strict` converts warnings into build failures. It is valuable as a project
policy or final clean-build gate, but it does not identify which change caused
an old warning.

1. Run the repository's normal build command and retain its warnings.
2. Compare with a pre-change run, CI history, or an unchanged revision when
   available.
3. Fix warnings introduced by the requested work.
4. Report unrelated warnings by message and affected path; do not suppress them
   or expand scope silently.
5. Run strict mode when the project requires it or after the warning set is
   understood.

## Preview versus deployment

`mkdocs serve` is a live-reload development server. A successful preview does
not verify the production base URL, generated artifact, CI dependencies,
case-sensitive filesystem, caching, redirects, or host configuration. Build the
site using production-equivalent inputs and inspect the actual publishing
workflow. Running that workflow still requires authorization because it changes
external state.

## Official references

- [MkDocs CLI](https://www.mkdocs.org/user-guide/cli/)
- [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/)
- [Material customization](https://squidfunk.github.io/mkdocs-material/customization/)
- [Material publishing](https://squidfunk.github.io/mkdocs-material/publishing-your-site/)
- [Material content tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/)