Build & Deployment Errors

This page covers errors that prevent MkDocs from building or deploying the site.

Problem: YAML Parse Error on mkdocs serve

Symptom: Running mkdocs serve fails immediately with an error like:

ERROR - yaml.scanner.ScannerError: while scanning a simple key
  in "mkdocs.yml", line 83, column 5

Cause: The mkdocs.yml file has a YAML syntax error. Common causes include tabs instead of spaces for indentation, colons in unquoted nav entry titles, unclosed quotes, and incorrect indentation levels.

Solutions:

Check for tabs vs spaces — YAML requires spaces. If your editor inserted a tab character, replace it with 2 spaces:

# WRONG (tab character)
theme:
→name: material

# CORRECT (2 spaces)
theme:
  name: material

Check for unquoted colons in nav titles:

# WRONG — colon in the title causes a parse error
nav:
  - Application Setup: Overview: configuration/applications.md

# CORRECT — wrap the title in quotes
nav:
  - "Application Setup: Overview": configuration/applications.md

Check for unclosed quotes:

# WRONG — missing closing quote
nav:
  - "Application Setup: configuration/applications.md

# CORRECT
nav:
  - "Application Setup": configuration/applications.md

Problem: Page Not Found Warning During Build

Symptom: mkdocs serve starts but shows warnings like:

WARNING - Doc file 'configuration/new-page.md' not found

Cause: The nav section in mkdocs.yml references a file that does not exist at the specified path.

Solutions:

Verify the filename and path in nav match the actual file on disk. Filenames are case-sensitive.
Check for typos in the path (e.g., confguration/ instead of configuration/).
Ensure the file has been created and saved before running mkdocs serve.

Problem: Missing Plugin Error

Symptom: Running mkdocs serve fails with:

ERROR - Config value 'plugins': The "glightbox" plugin is not installed

Cause: The plugin listed in mkdocs.yml is not installed in the Python environment.

Solution: Install the missing plugin:

pip install mkdocs-glightbox

Common plugins used in EPMware docs and their install commands:

Plugin	Install Command
Material theme	`pip install mkdocs-material`
Glightbox	`pip install mkdocs-glightbox`
Search (built-in)	Included with MkDocs

Virtual Environments

If you use Python virtual environments, make sure the environment is activated before installing plugins and running mkdocs serve.

Problem: GitHub Actions Build Fails

Symptom: The deployment workflow shows a red ✗ on the GitHub Actions tab.

Solutions:

Click on the failed workflow run to see the error logs. Common causes:

Missing plugin in the workflow: If you added a new plugin to mkdocs.yml, you must also add it to the pip install line in .github/workflows/deploy.yml:

# Before
- run: pip install mkdocs-material mkdocs-glightbox

# After (adding a new plugin)
- run: pip install mkdocs-material mkdocs-glightbox new-plugin-name

Python version issue: If the workflow uses an outdated Python version, update the setup-python step:

- uses: actions/setup-python@v5
  with:
    python-version: '3.x'

Permission error: Ensure the workflow has write permissions to deploy:

permissions:
  contents: write

Problem: GitHub Actions Deprecation Warnings

Symptom: The GitHub Actions build succeeds but shows warnings like:

Node.js 16 actions are deprecated. Please update the following actions to use Node.js 20:
  actions/checkout@v3, actions/setup-python@v4

Cause: The workflow file references older versions of GitHub Actions that are being deprecated.

Solution: Update the action version numbers in .github/workflows/deploy.yml:

# Old versions (deprecated)
- uses: actions/checkout@v3
- uses: actions/setup-python@v4

# Updated versions
- uses: actions/checkout@v4
- uses: actions/setup-python@v5

Upstream Deprecation

These deprecation warnings are from GitHub, not from MkDocs. They do not prevent deployment but should be addressed to avoid future breakage when GitHub removes support for older Node.js versions.

Problem: Site Deploys But Shows Old Content

Symptom: GitHub Actions shows a successful build, but the live site still shows the previous version of a page.

Cause: Browser caching or GitHub Pages CDN caching.

Solutions:

Hard refresh your browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).
Clear browser cache for the site.
Wait a few minutes — GitHub Pages can take up to 10 minutes to propagate changes through its CDN.
Check the GitHub Actions logs to confirm the build included your latest commit.

Problem: mkdocs build Succeeds But Site Looks Wrong

Symptom: The build completes without errors, but pages display incorrectly — missing styles, broken layout, or missing navigation.

Cause: The custom.css file may have a syntax error, or a theme configuration change may have removed a required feature.

Solutions:

Check custom.css for syntax errors (unclosed braces, missing semicolons).
Verify the extra_css path in mkdocs.yml points to the correct file.
Review recent changes to the theme section in mkdocs.yml and revert if needed.
Open your browser's developer tools (F12) and check the Console tab for CSS or JavaScript errors.