Skip to content

Troubleshooting

This page covers the most common problems and the first things to check.

Build failed

Symptom: The build process exits with an error.

Try this:

  • Read the Build panel output from top to bottom. The first error is usually the important one.
  • Check that mkdocs.yml is valid YAML.
  • Make sure every page listed in navigation exists.
  • Check for missing images or broken relative links.
  • If your project uses unusual MkDocs plugins or extensions, make sure they are supported by your current runtime.

About Python and MkDocs

The Windows installer includes an app-managed MkDocs runtime. Normal users should not need to install Python or MkDocs manually. Manual Python/MkDocs setup is mainly for developers, source builds, or advanced custom environments.

Preview server does not start

Symptom: The full site preview or local serve action does not open.

Try this:

  • Check if another process is already using port 8000.
  • Stop other MkDocs servers you started manually.
  • Restart the local preview from the Build panel.
  • Restart MkLume if the server process got stuck.

Images do not show

Symptom: Images appear broken in preview or in the built site.

Try this:

  • Confirm the image file exists inside your project docs/ folder.
  • Use relative paths, for example:
![Alt text](assets/my-image.png)
  • Check capitalization. Some hosts are case-sensitive, so Image.png and image.png are not always the same.
  • Avoid linking to images on your desktop or outside the docs project.

Smart links do not find a page

Symptom: The internal link search does not show a page you expect.

Try this:

  • Make sure the target file exists inside the current project docs/ folder.
  • Check that it uses the .md extension.
  • Save newly created files before searching for them.
  • Reopen the project if the file index seems stale.

Git Sync failed

Symptom: Commit, push, or pull fails.

Try this:

  • Install Git and make sure it is available in your system PATH.
  • Make sure the project is a Git repository.
  • Check your remote URL.
  • Confirm your Git credentials work outside MkLume.

MkLume uses your local Git setup. It does not store GitHub tokens, passwords, or personal access tokens.

Git authentication failed

Symptom: Push or pull fails with a permission error.

Try this:

  • For HTTPS, use your normal Git credential manager.
  • For SSH, make sure your SSH key is added to your Git host and your SSH agent is running.
  • Test git push in a terminal from the same project folder.

GitHub Pages workflow failed

Symptom: The GitHub Actions workflow fails after using the deploy assistant.

Try this:

  • Open the Actions tab on GitHub and read the failing step.
  • Make sure GitHub Pages is enabled.
  • Set the Pages source to GitHub Actions.
  • Check that the generated workflow file is committed to .github/workflows/.
  • If your project needs extra Python packages, add them to requirements.txt.

Site Settings YAML error

Symptom: MkLume reports a YAML parsing error after editing site settings.

Try this:

  • Check indentation. YAML uses spaces, not tabs.
  • Quote values that contain special characters like : or #.
  • Look for missing dashes in lists.
  • Revert the last manual edit if the error started after editing mkdocs.yml by hand.

Recovery draft found

Symptom: MkLume asks whether to restore a recovery draft.

What happened: MkLume saved a draft before the app closed unexpectedly or before unsaved changes were lost.

Choose:

  • Restore if you want to recover the draft.
  • Discard if the saved file on disk is the version you want to keep.

Recovery files are stored inside the project .mklume/ folder.

App shows a blank or black screen

Symptom: MkLume opens but the window is blank, black, or unresponsive.

Try this:

  • Restart MkLume.
  • Restart your computer if WebView2 or GPU acceleration is stuck.
  • On Windows, make sure Microsoft Edge WebView2 is installed and up to date.
  • Update your graphics drivers.

Windows SmartScreen warning

Symptom: Windows says the app is from an unknown publisher.

MkLume is not code-signed yet. This warning can appear for new unsigned open-source applications.

Use the official GitHub Releases page and compare the checksum shown there if you want to verify the installer.

To continue, click More info and then Run anyway.

Where to report issues

Please report bugs and feature requests on GitHub Issues. Include:

  • MkLume version, for example 1.0.1.
  • Windows/macOS/Linux version.
  • What you were doing.
  • The error message or screenshot.
  • Whether it happens in one project or every project.