Projects plugin - KeyError

[alexvoss]

Context

Building the examples as well as the minimal reproduction attached below.

Bug description

I get a KeyError every time a project gets re-built:

mkdocs serve 
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.33 seconds
INFO    -  [17:46:59] Watching paths for changes: 'docs', 'mkdocs.yml', 'projects/tutorial/docs', 'projects/tutorial/mkdocs.yml'
INFO    -  [17:46:59] Serving on http://127.0.0.1:8000/
Exception in thread Thread-2:
Traceback (most recent call last):
  File "/opt/homebrew/Cellar/python@3.11/3.11.5/Frameworks/Python.framework/Versions/3.11/lib/python3.11/threading.py", line 1038, in _bootstrap_inner
INFO    -  [17:47:25] Detected file changes
    self.run()
  File "/Users/avoss/src/mkdocs-material/examples/venv/lib/python3.11/site-packages/watchdog/observers/api.py", line 204, in run
    self.dispatch_events(self.event_queue)
  File "/Users/avoss/src/mkdocs-material/examples/venv/lib/python3.11/site-packages/watchdog/observers/api.py", line 380, in dispatch_events
    handler.dispatch(event)
  File "/Users/avoss/src/mkdocs-material/examples/venv/lib/python3.11/site-packages/watchdog/events.py", line 275, in dispatch
    self.on_any_event(event)
  File "/Users/avoss/src/mkdocs-material/examples/venv/lib/python3.11/site-packages/material/plugins/projects/plugin.py", line 314, in resolve
    del self.pool_jobs[slug]
        ~~~~~~~~~~~~~~^^^^^^
KeyError: '.tutorial'
INFO    -  Building documentation...
INFO    -  [17:47:25] Reloading browsers

Related links

• Reporting a bug
• Projects plugin

Reproduction

9.4.5+insiders.4.42.1-projects-plugin-keyerror.zip

Steps to reproduce

1. Make sure to use the insiders edition (I used the latest from the repo)
2. Run mkdocs serve
3. Create a new Markdown file in the subproject
4. Observe KeyError on the console

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction.

[squidfunk]

Thanks for reporting. Did you create a new project or only a Markdown file inside an existing project? I'm confused, because the projects plugin doesn't seem to have seen the project, since the slug does not exist.

[alexvoss]

To trigger the behaviour I only added a new Markdown page to the existing subproject tutorial. I just tried creating an entirely new project with mkdocs new test and nothing happens. Would be good if it picked up new projects while running as well.

I was wondering about the dot at the beginning of the name it is trying to find but perhaps slugs are supposed to have that. I can try and debug but thought you might spot the problem with your eagle eyes.

For now I can work around it by restarting mkdocs, so not a blocker but it is a bit tedious.

[squidfunk]

I was wondering about the dot at the beginning of the name it is trying to find but perhaps slugs are supposed to have that. I can try and debug but thought you might spot the problem with your eagle eyes.

Slugs are only used internally and the dot is a special notation I came up with:

.        # root
.foo     # projects/foo
.foo.bar # projects/foo/projects/bar

It's important to have a way to resolve the root from any other project, which is why . is the prefix for every slug that is resolved from the root. In the next iterations, we'll be adding further relative resolution capabilities for URLs and friends.

[alexvoss]

Will get a debugger out today and have a look to see if I can stop what is going on. Obviously, the tutorial subproject is getting picked up, its contents are being watched but something goes wrong in that process. I have tried making changes in other subprojects of the examples repo and the problem does not occur. So, something I neglected to do in tutorial?

[squidfunk]

I'm pretty sure the problem is in the on_serve handler: the handler tries to resolve the slug of the project and somehow can't do it. Let me check.

[squidfunk]

Fixed in 4e376c447. What happened was that two events are triggered when a file is added or removed:

• <FileCreatedEvent: event_type=created>
• <DirModifiedEvent: event_type=modified>

The first event removed the project from the job pool, so that it is rebuilt, and the second event tried to do the same again, but since the project has not yet been rebuilt this triggered a key error. The commit changes the behavior to be a no-op if the project has already been scheduled for rebuilding. My testing shows that the reported behavior is gone, and you can easily add or remove files from projects.

[alexvoss]

I can confirm this solved the issue for me. Thanks a lot for the quick fix!

[squidfunk]

We keep issues open until the fixes are released ☺️ This approach signals to users that a fix for the reported issue is available to use on the latest master, but has not been released yet. When the fix or change request is released, we close the issue with a note which version contains the relevant commits.

[squidfunk]

Released as part of 9.4.6+insiders-4.42.2.