Problem in get_doc_context() (non-existent docname?)

Dirkjan Ochtman avatarDirkjan Ochtman created an issue
# Sphinx version: 1.1.3
# Python version: 2.7.5
# Docutils version: 0.10 release
# Jinja2 version: 2.7
Traceback (most recent call last):
  File "/usr/lib/python2.7/site-packages/sphinx/", line 189, in main, filenames)
  File "/usr/lib/python2.7/site-packages/sphinx/", line 204, in bu                            ild
  File "/usr/lib/python2.7/site-packages/sphinx/builders/", line 196,                             in build_update
    'out of date' % len(to_build))
  File "/usr/lib/python2.7/site-packages/sphinx/builders/", line 252,                             in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python2.7/site-packages/sphinx/builders/", line 292,                             in write
    self.write_doc(docname, doctree)
  File "/usr/lib/python2.7/site-packages/sphinx/builders/", line 424, in                             write_doc
    ctx = self.get_doc_context(docname, body, metatags)
  File "/usr/lib/python2.7/site-packages/sphinx/builders/", line 407, in                             get_doc_context
    display_toc = (self.env.toc_num_entries[docname] > 1),
KeyError: 'api-basics'

Comments (4)

  1. Georg Brandl

    That's because we now delete all cached stuff when an exception occurs during build, so that a full rebuild has to be done.

    These KeyErrors are annoying, and I also get them from time to time when adding or removing files. I'd like to track them down, but at least people don't get stuck anymore and have to remove their doctrees by hand.

  2. Brad King

    I ran into this issue with the exact same stack trace and tracked it down. It happens when:

    • Using the html builder, having already completed a build
    • A document has been removed since the last build
    • The html .buildinfo config or tags hash has changed

    The pickled environment is loaded with found_docs containing the now-removed document. Then the html builder's get_outdated_docs, in the code path for changed config/tags, yields everything in found_docs without checking whether the document files still exist. This patch fixes it:

    diff -r e5e3a44d334a sphinx/builders/
    --- a/sphinx/builders/   Sat Oct 12 22:57:09 2013 +0200
    +++ b/sphinx/builders/   Thu Oct 17 10:27:16 2013 -0400
    @@ -196,7 +196,8 @@
             if old_config_hash != self.config_hash or \
                    old_tags_hash != self.tags_hash:
                 for docname in self.env.found_docs:
    -                yield docname
    +                if path.exists(self.env.doc2path(docname)):
    +                    yield docname
             if self.templates:
  3. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.