What causes "Relative path processor not registered" in squidfunk/mkdocs-material?

Pin the markdown package to a version compatible with your mkdocs-material release (check material's requirements).

squidfunk/mkdocs-material · error · TypeError

Relative path processor not registered

Error message

Relative path processor not registered

What it means

The preview extension's run() hooks into Markdown conversion and relies on markdown's built-in _RelativePathTreeprocessor to know the current page's file path. It looks the processor up in md.treeprocessors and throws a TypeError if the registered processor at that priority slot is not the expected _RelativePathTreeprocessor. This happens when the markdown library's internal pipeline changes (different version or competing extensions).

Source

Thrown at src/extensions/preview.py:76

        Run the treeprocessor.

        Arguments:
            root: The root element of the parsed Markdown document.
        """
        at = self.md.treeprocessors.get_index_for_name("relpath")

        # Hack: Python Markdown has no notion of where it is, i.e., which file
        # is being processed. This seems to be a deliberate design decision, as
        # it is not possible to access the file path of the current page, but
        # it might also be an oversight that is now impossible to fix. However,
        # since this extension is only useful in the context of Material for
        # MkDocs, we can assume that the _RelativePathTreeprocessor is always
        # present, telling us the file path of the current page. If that ever
        # changes, we would need to wrap this extension in a plugin, but for
        # the time being we are sneaky and will probably get away with it.
        processor = self.md.treeprocessors[at]
        if not isinstance(processor, _RelativePathTreeprocessor):
            raise TypeError("Relative path processor not registered")

        # Normalize configurations
        configurations = self.config["configurations"]
        configurations.append({
            "sources": self.config.get("sources"),
            "targets": self.config.get("targets")
        })

        # Walk through all configurations - @todo refactor so that we don't
        # iterate multiple times over the same elements
        for configuration in configurations:

            # Skip, if the configuration defines nothing – we could also fix
            # this in the file filter, but we first fix it here and check if
            # it generalizes well enough to other inclusion/exclusion sites,
            # because here, it would hinder the ability to automaticaly
            # include all sources, while excluding specific targets.
            if (

View on GitHub (pinned to e2136532f4)

Solutions

Pin the markdown package to a version compatible with your mkdocs-material release (check material's requirements).
Disable or reorder third-party Markdown extensions that register treeprocessors at the same priority slot.
If you maintain the integration, look the processor up by class name instead of a fixed priority key.

Example fix

# before (requirements.txt)
markdown>=3.3

# after
markdown>=3.3,<3.5

Defensive patterns

Strategy: validation

Validate before calling

import markdown
from mkdocs_extensions_preview import _RelativePathTreeprocessor
md = markdown.Markdown(extensions=[...])
assert any(isinstance(p, _RelativePathTreeprocessor) for p in md.treeprocessors), (
    "markdown version incompatible: relative path treeprocessor missing"
)

Type guard

def is_relative_path_processor(md) -> bool:
    proc = md.treeprocessors[150] if 150 in md.treeprocessors else None
    return isinstance(proc, _RelativePathTreeprocessor)

Try / catch

try:
    extensions = [Preview()]  # or via mkdocs.yml
except TypeError as e:
    if "Relative path processor" in str(e):
        # markdown version mismatch: pin/downgrade markdown
        raise SystemExit("Upgrade/downgrade the 'markdown' package")
    raise

Prevention

Pin the markdown dependency to the range mkdocs-material declares in its requirements.
Test mkdocs builds in CI after any dependency bump.
Avoid extensions that hijack the same treeprocessor priority slot.
Read changelogs of the markdown package before upgrading.

When it happens

Trigger: Running preview with a markdown/Markdown version where _RelativePathTreeprocessor is no longer registered at the expected priority; another extension registering a treeprocessor at that slot; markdown internals refactored/renamed in an upgrade.

Common situations: Upgrading the markdown package beyond what mkdocs-material supports; installing plugins that inject custom treeprocessors at the same priority; running mkdocs against an unusual/newer markdown release.

Related errors

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/7bc84dff3254f459. Report an issue: GitHub.