Issue building or serving mkdocs-material version 9.2 or higher showing jinja2 error

Question

I have been using mkdocs with the material theme for a small project. I recently updated to the latest build and then started seeing an error. I found that, on my Mac, any version after 9.2 threw the same set of errors as soon as the theme was set.

I found that the site will build with mkdocs version 1.5.3 and mkdocs-material version 9.1.21. Nothing later for this theme will work they all through the error shown below.

How can I fix this?

Here is the error:

❯ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory:
           /Users/username/Documents/Sites/Repos/bitbucket_fs/source_lms/site
Traceback (most recent call last):
  File "/Library/Frameworks/Python.framework/Versions/3.12/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/mkdocs/__main__.py", line 286, in build_command
    build.build(cfg, dirty=not clean)
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/mkdocs/commands/build.py", line 340, in build
    _build_theme_template(template, env, files, config, nav)
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/mkdocs/commands/build.py", line 110, in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/mkdocs/commands/build.py", line 89, in _build_template
    output = template.render(context)
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/Users/Username/Documents/Sites/Repos/bitbucket_fs/source_lms_faculty/docs/theme_mod/404.html", line 5, in top-level template code
    {% extends "main.html" %}
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/material/main.html", line 4, in top-level template code
    {% extends "base.html" %}
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/material/base.html", line 59, in top-level template code
    {% block fonts %}
^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/material/base.html", line 61, in block 'fonts'
    {% set text = config.theme.font.get("text", "Roboto") %}
^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/jinja2/utils.py", line 83, in from_obj
    if hasattr(obj, "jinja_pass_arg"):
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
jinja2.exceptions.UndefinedError: 'list object' has no attribute 'get'

I tried:

• Uninstalling both mkdocs and mkdocs-material theme.
• Ran mkdocs without them applied, and it works.
• Installed mkdocs-material 9.1.21, and it builds well
• Updated to mkocs-material 9.2 or any later version and it fails

Research

I checked several sites online, trying to find any post that relates to an issue with this version and any of the errors that were listed, but I couldn't find anything solid. I reviewed the documentation for both, but I still can't find any related information.

Answer 1

The issue is less with mkdocs and its fabulous material theme, but more a simple code incompatibility with the Python interpreter in action.

As the diverse paths in the stack trace you've shared inherently suggest you're running on the incarnation version 3.12.

Note: mkdocs --version should show the concrete Python interpreter as well. This is handy to track the setup.

If I may suggest to obtain an older version that the development has been battle-proven with over the last decade in that to find a more stable setup.

Off the top of my head, 3.10 should work, and if establishing such versions for the setup performs cumbersome, you may choose to build with the mkdocs material container.

The other alternative is to use the power of the virtual environment, and it's ca. since Python 3 it ships with by the name of the module that is venv, but then you require the python version (the specific, e.g. 3.10, 3.9 , 3.11, ...) as well.

I normally prefer a venv setup and then pin the Python (and all other like mkdocs, material, the plugins and additional libraries) versions so that once the build worked, it does not break.

You can emulate that by pinning the version of the docker container if you opt into the overhead of throwing images around, just use a stable tag or more decent, the hash.

---

And seeing it's from Jinja: Check with any of the templates and making use of variables therein. You've either discovered a pretty rare bug or—perhaps more likely—pass some data into the template (e.g., a list instead of an object), that summons the error from the context (the template context contains the variables and if you look into mkdocs sources, you can find where this passes from during building the HTML pages, it is relatively straightforward).

If you can quickly double check edits in the configuration document or use of plugins that make use of data provided in the configuration, that is often a good starting point for first quick guesses.