Skip to content

AssertionError when using a :confval: reference inside a .. confval :default: #14117

@bluetech

Description

@bluetech

Describe the bug

Given a file like this:

.. confval: conf1

   Description of conf1.

.. confval: conf2
   .. default: Fallback to :confval:`conf1`

   Description of conf2.

I get this error:

Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 774, in write_process
        self.write_doc(docname, doctree)
        ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/sphinx/builders/html/__init__.py", line 670, in write_doc
        self.docwriter.write(doctree, destination)
        ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/docutils/writers/__init__.py", line 80, in write
        self.translate()
        ~~~~~~~~~~~~~~^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/sphinx/writers/html.py", line 36, in translate
        self.document.walkabout(visitor)
        ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/docutils/nodes.py", line 186, in walkabout
        if child.walkabout(visitor):
           ~~~~~~~~~~~~~~~^^^^^^^^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/docutils/nodes.py", line 186, in walkabout
        if child.walkabout(visitor):
           ~~~~~~~~~~~~~~~^^^^^^^^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/docutils/nodes.py", line 186, in walkabout
        if child.walkabout(visitor):
           ~~~~~~~~~~~~~~~^^^^^^^^^
      [Previous line repeated 5 more times]
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/docutils/nodes.py", line 178, in walkabout
        visitor.dispatch_visit(self)
        ~~~~~~~~~~~~~~~~~~~~~~^^^^^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/sphinx/util/docutils.py", line 767, in dispatch_visit
        method(node)
        ~~~~~~^^^^^^
      File "/home/ran/src/pytest/.tox/docs/lib/python3.13/site-packages/sphinx/writers/html5.py", line 342, in visit_reference
        assert len(node) == 1 and isinstance(node[0], nodes.image)  # NoQA: PT018
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    AssertionError

I was able to figure out that it was caused by the :confval: in the :default: eventually, but reporting it as per the request to "Please also report this if it was a user error, so that a better error message can be provided next time." 😀

How to Reproduce

This happened in the pytest after trying to add a default like the above. Pytest docs can be built using tox -e docs.

Environment Information

Versions
========

* Platform:         linux; (Linux-6.17.8-arch1-1-x86_64-with-glibc2.42)
* Python version:   3.13.7 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.21.2
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Sphinx extensions

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* pygments_pytest (unknown version)
* sphinx.ext.autodoc.preserve_defaults (8.2.3)
* sphinx.ext.autodoc.type_comment (8.2.3)
* sphinx.ext.autodoc.typehints (8.2.3)
* sphinx.ext.autodoc (8.2.3)
* sphinx.ext.autosummary (8.2.3)
* sphinx.ext.intersphinx (8.2.3)
* sphinx.ext.todo (8.2.3)
* sphinx.ext.viewcode (8.2.3)
* sphinx_removed_in (0.2.3)
* sphinx_inline_tabs (2023.04.21)
* sphinxcontrib_trio (1.1.2)
* sphinxcontrib.towncrier.ext (0.5.0a0)
* sphinx_issues (5.0.1)
* furo (2025.09.25)
* sphinx_basic_ng (1.0.0.beta2)

Additional context

Last Messages
=============

    how-to/failures .. how-to/skipping


    writing output... [ 92%]
    how-to/subtests .. proposals/parametrize_with_fixtures


    writing output... [ 96%]
    recwarn .. tidelift

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions