Live reload crashes if mkdocs.yml have error, and never goes live, even when mkdocs.yml is fixed

[artem-korolev]

Hi,

I got this issue. When I edit mkdocs.yml and make syntax/other mistake in it. It reads mkdocs.yml again and again and never goes live anymore.

Seems like a bug

[waylan]

Does it "crash" or exit? A crash would cause an error and traceback to be reported. What it should be doing in that case is exiting with a nicely formatted error message. After fixing the problem, then you would need to relaunch the server.

Could you provide an example of an error in the YAML that creates the problem and a copy of the console output?

[artem-korolev]

Sorry. You right. I forgot to provide an error log. That is:
I use latest version of this docker image - https://hub.docker.com/r/squidfunk/mkdocs-material/

INFO    -  Building documentation...
[E 180711 11:25:36 ioloop:638] Exception in callback <bound method type.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
    Traceback (most recent call last):
      File "/usr/lib/python2.7/site-packages/tornado-4.5.3-py2.7-linux-x86_64.egg/tornado/ioloop.py", line 1026, in _run
        return self.callback()
      File "/usr/lib/python2.7/site-packages/livereload-2.5.2-py2.7.egg/livereload/handlers.py", line 66, in poll_tasks
        filepath, delay = cls.watcher.examine()
      File "/usr/lib/python2.7/site-packages/livereload-2.5.2-py2.7.egg/livereload/watcher.py", line 93, in examine
        func()
      File "/usr/lib/python2.7/site-packages/mkdocs-0.17.4-py2.7.egg/mkdocs/commands/serve.py", line 104, in builder
        theme_dir=theme_dir
      File "/usr/lib/python2.7/site-packages/mkdocs-0.17.4-py2.7.egg/mkdocs/config/base.py", line 177, in load_config
        cfg.load_file(config_file)
      File "/usr/lib/python2.7/site-packages/mkdocs-0.17.4-py2.7.egg/mkdocs/config/base.py", line 123, in load_file
        return self.load_dict(utils.yaml_load(config_file))
      File "/usr/lib/python2.7/site-packages/mkdocs-0.17.4-py2.7.egg/mkdocs/utils/__init__.py", line 71, in yaml_load
        return yaml.load(source, Loader)
      File "build/bdist.linux-x86_64/egg/yaml/__init__.py", line 71, in load
        return loader.get_single_data()
      File "build/bdist.linux-x86_64/egg/yaml/constructor.py", line 37, in get_single_data
        node = self.get_single_node()
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 36, in get_single_node
        document = self.compose_document()
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 55, in compose_document
        node = self.compose_node(None, None)
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 84, in compose_node
        node = self.compose_mapping_node(anchor)
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 133, in compose_mapping_node
        item_value = self.compose_node(node, item_key)
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 84, in compose_node
        node = self.compose_mapping_node(anchor)
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 133, in compose_mapping_node
        item_value = self.compose_node(node, item_key)
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 82, in compose_node
        node = self.compose_sequence_node(anchor)
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 111, in compose_sequence_node
        node.value.append(self.compose_node(node, index))
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 84, in compose_node
        node = self.compose_mapping_node(anchor)
      File "build/bdist.linux-x86_64/egg/yaml/composer.py", line 127, in compose_mapping_node
        while not self.check_event(MappingEndEvent):
      File "build/bdist.linux-x86_64/egg/yaml/parser.py", line 98, in check_event
        self.current_event = self.state()
      File "build/bdist.linux-x86_64/egg/yaml/parser.py", line 439, in parse_block_mapping_key
        "expected <block end>, but found %r" % token.id, token.start_mark)
    ParserError: while parsing a block mapping
      in "/docs/mkdocs.yml", line 16, column 11
    expected <block end>, but found '<block mapping start>'
      in "/docs/mkdocs.yml", line 17, column 13
[I 180711 11:25:37 watcher:92] Running task: <function builder at 0x7f8d2d0ee9b0> (delay: None)
INFO    -  Building documentation...
[E 180711 11:25:37 ioloop:638] Exception in callback <bound method type.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
    Traceback (most recent call last):
      File "/usr/lib/python2.7/site-packages/tornado-4.5.3-py2.7-linux-x86_64.egg/tornado/ioloop.py", line 1026, in _run
        return self.callback()

configuration is very basic. Default. with repo link and "material" as theme. And then I added there incorrect yaml. exactly this one:

extra:
    social:
        - type: 'github'
        link: 'https://github.com/squidfunk'
        - type: 'twitter'
        link: 'https://twitter.com/squidfunk'
        - type: 'linkedin'
        link: 'https://linkedin.com/in/squidfunk'

it started to constantly writing above output into log. Then I fixed the yaml like this:

extra:
    social:
        - type: 'github'
          link: 'https://github.com/squidfunk'
        - type: 'twitter'
          link: 'https://twitter.com/squidfunk'
        - type: 'linkedin'
          link: 'https://linkedin.com/in/squidfunk'

this didn't fixed the issue. To fix the issue I restarted my docker container. After that mkdocs successfully read the config and all works fine.

I will try to reproduce it again, if you are not able to do it yourown

[waylan]

Ah, I see. You started the server with a valid config, then made an edit which broke the config and that crashed the server such that additional edits to the config were not picked up. I've seen that behavior before, although it is difficult to nail down/debug. I believe the correct approach is that the server should stop and exit when a bad edit to the config happens.

It can be tricky as the server relies on some of the pieces of the config before it can start. So when the config is later altered, it can confuse the server as we end up with a circular dependency issue. Whenever I need to edit the config, I find it best to stop the server first, make my edit, and then restart. But we could do a better job of handling these sorts of errors.

[waylan]

I can't seem to get MkDocs to fail to reload the config. In #1546 I was able to modify MkDocs to catch the YAML parser error to provide a cleaner error message, but it appears that we would need to modify the "file watcher" to actually stop/restart the server. And the "file watcher" is part of lepture/python-livereload. In the end, this seems to be an upstream issue.

Or possibly, the problem is in the docker config, in which case that would be an upstream issue with whoever put that together.

Here is a server session I tried after applying the the change in #1546:

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 180712 11:22:46 server:283] Serving on http://127.0.0.1:8000
[I 180712 11:22:46 handlers:60] Start watching changes
[I 180712 11:22:46 handlers:62] Start detecting changes
INFO    -  Building documentation...
[E 180712 11:22:52 ioloop:793] Exception in callback <bound method type.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
    Traceback (most recent call last):
      File "c:\users\wlimberg\documents\github\mkdocs\venv\lib\site-packages\tornado\ioloop.py", line 1209, in _run
        return self.callback()
      File "c:\users\wlimberg\documents\github\mkdocs\venv\lib\site-packages\livereload\handlers.py", line 67, in poll_tasks
        filepath, delay = cls.watcher.examine()
      File "c:\users\wlimberg\documents\github\mkdocs\venv\lib\site-packages\livereload\watcher.py", line 73, in examine
        func and func()
      File "c:\users\wlimberg\documents\github\mkdocs\mkdocs\commands\serve.py", line 107, in builder
        site_dir=site_dir
      File "c:\users\wlimberg\documents\github\mkdocs\mkdocs\config\base.py", line 192, in load_config
        cfg.load_file(config_file)
      File "c:\users\wlimberg\documents\github\mkdocs\mkdocs\config\base.py", line 137, in load_file
        "MkDocs encountered as error parsing the configuration file: {}".format(e)
    ConfigurationError: MkDocs encountered as error parsing the configuration file: mapping values are not allowed here
      in "C:\Users\wlimberg\Documents\GitHub\mkdocs\mkdocs.yml", line 9, column 9
INFO    -  Building documentation...

In the above session, the server was started with a valid config. An edit was made to the config file, resulting in the second INFO - Building documentation... line and the error that immediately follows. A second edit to the config (fixing the problem) then resulted in the final INFO - Building documentation... and things work fine from that point forward.

Compare that with the output if the config is bad when the server is first started:

$ mkdocs serve
INFO    -  Building documentation...

MkDocs encountered as error parsing the configuration file: mapping values are not allowed here
  in "C:\Users\wlimberg\Documents\GitHub\mkdocs\mkdocs.yml", line 9, column 9

It appears that python-livereload simply catches the error and writes the entire traceback to the server log. But there is no way to tell python-livereload to stop the server on certain types of errors or to omit the traceback.

And the fact that fixing the config seems to allow the server to continue working properly (outside of Docker) suggests that the reported problem is probably related to Docker more than MkDocs. At least it would suggest an incompatibility between python-livereload and Docker. Either way, that would need to be addressed upstream with either or both of those tools.

[pawamoy]

This was implemented in v1.5: https://www.mkdocs.org/about/release-notes/#mkdocs-serve-no-longer-exits-after-build-errors. Note however that this requires a first successful build to enter the loop, which could be considered a limitation. I'll close this as completed, please open a new issue if you'd like to always enter the rebuild loop, even if the first build fails.