C++ domain: assertion failure in _resolve_xref_inner

[mhekkel]

Describe the bug

I'm trying to generate documentation for my project mxml but this fails due to an AssertionError. Log file is attached.

sphinx-err-0k0_hib9.log

How to Reproduce

git clone https://github.com/mhekkel/mxml
cd mxml
cmake -B build -DMXML_BUILD_DOCUMENTATION=ON
cmake --build

Environment Information

Platform:              linux; (Linux-6.12.57+deb13-amd64-x86_64-with-glibc2.41)
Python version:        3.13.5 (main, Jun 25 2025, 18:55:22) [GCC 14.2.0])
Python implementation: CPython
Sphinx version:        8.1.3
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.18.0

Sphinx extensions

Additional context

# Platform:         linux; (Linux-6.12.57+deb13-amd64-x86_64-with-glibc2.41)
# Sphinx version:   8.1.3
# Python version:   3.13.5 (CPython)
# Docutils version: 0.21.2
# Jinja2 version:   3.1.6
# Pygments version: 2.18.0

# Last messages:
#   
#   writing output... [ 85%]
#   api/structmxml_1_1type__serializer
#   
#   writing output... [ 86%]
#   api/structmxml_1_1value__serializer
#   
#   writing output... [ 87%]
#   api/structmxml_1_1value__serializer_3_01T_01_4
#   

# Loaded extensions:
#   sphinx.ext.mathjax (8.1.3)
#   alabaster (0.7.16)
#   breathe (4.35.0)
#   exhale (0.3.7)
#   myst_parser (4.0.1)
#   sphinxcontrib.jquery (4.1)
#   sphinx_rtd_theme (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/cmd/build.py", line 514, in build_main
    app.build(args.force_all, args.filenames)
    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/application.py", line 380, in build
    self.builder.build_update()
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 358, in build_update
    self.build(
    ~~~~~~~~~~^
        to_build,
        ^^^^^^^^^
        summary=__('targets for %d source files that are out of date')
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        % len(to_build),
        ^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 437, in build
    self.write(docnames, list(updated_docnames), method)
    ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 711, in write
    self.write_documents(docnames)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 725, in write_documents
    self._write_serial(sorted_docnames)
    ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 741, in _write_serial
    doctree = self.env.get_and_resolve_doctree(docname, self)
  File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 661, in get_and_resolve_doctree
    self.apply_post_transforms(doctree, docname)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 729, in apply_post_transforms
    transformer.apply_transforms()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/sphinx/transforms/__init__.py", line 94, in apply_transforms
    super().apply_transforms()  # type: ignore[misc]
    ~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/docutils/transforms/__init__.py", line 182, in apply_transforms
    transform.apply(**kwargs)
    ~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/transforms/post_transforms/__init__.py", line 44, in apply
    self.run(**kwargs)
    ~~~~~~~~^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/transforms/post_transforms/__init__.py", line 90, in run
    newnode = domain.resolve_xref(
        self.env, refdoc, self.app.builder, typ, target, node, contnode
    )
  File "/usr/lib/python3/dist-packages/sphinx/domains/cpp/__init__.py", line 1111, in resolve_xref
    return self._resolve_xref_inner(env, fromdocname, builder, typ,
           ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                    target, node, contnode)[0]
                                    ^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/domains/cpp/__init__.py", line 996, in _resolve_xref_inner
    assert parentSymbol  # should be there
           ^^^^^^^^^^^^
AssertionError

[mhekkel]

I can work around this issue by commenting out (for doxygen) one of the template specialisations. To reproduce, you will therefore have to check out the tag v2.0.3 of mxml.

[AA-Turner]

cc @jakobandersen

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/cmd/build.py", line 514, in build_main
    app.build(args.force_all, args.filenames)
    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/application.py", line 380, in build
    self.builder.build_update()
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 358, in build_update
    self.build(
    ~~~~~~~~~~^
        to_build,
        ^^^^^^^^^
        summary=__('targets for %d source files that are out of date')
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        % len(to_build),
        ^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 437, in build
    self.write(docnames, list(updated_docnames), method)
    ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 711, in write
    self.write_documents(docnames)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 725, in write_documents
    self._write_serial(sorted_docnames)
    ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 741, in _write_serial
    doctree = self.env.get_and_resolve_doctree(docname, self)
  File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 661, in get_and_resolve_doctree
    self.apply_post_transforms(doctree, docname)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 729, in apply_post_transforms
    transformer.apply_transforms()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/sphinx/transforms/__init__.py", line 94, in apply_transforms
    super().apply_transforms()  # type: ignore[misc]
    ~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/docutils/transforms/__init__.py", line 182, in apply_transforms
    transform.apply(**kwargs)
    ~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/transforms/post_transforms/__init__.py", line 44, in apply
    self.run(**kwargs)
    ~~~~~~~~^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/transforms/post_transforms/__init__.py", line 90, in run
    newnode = domain.resolve_xref(
        self.env, refdoc, self.app.builder, typ, target, node, contnode
    )
  File "/usr/lib/python3/dist-packages/sphinx/domains/cpp/__init__.py", line 1111, in resolve_xref
    return self._resolve_xref_inner(env, fromdocname, builder, typ,
           ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                    target, node, contnode)[0]
                                    ^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/domains/cpp/__init__.py", line 996, in _resolve_xref_inner
    assert parentSymbol  # should be there
           ^^^^^^^^^^^^
AssertionError

[AA-Turner]

@mhekkel note you are using an old version of Sphinx; we only provide support for the latest. Please can you confirm the errror still exists with Sphinx 9.0?

A

[mhekkel]

If I use pip install sphinx I get version 8. How am I supposed to get version 9?

[mhekkel]

Ah, managed to install 9. Same error:

Versions
========

* Platform:         linux; (Linux-6.17.8+deb14-amd64-x86_64-with-glibc2.41)
* Python version:   3.13.9 (CPython)
* Sphinx version:   9.0.1
* Docutils version: 0.21.2
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

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


    writing output... [ 80%]
    api/structmxml_1_1type__serializer

    writing output... [ 81%]
    api/structmxml_1_1value__serializer

    writing output... [ 82%]
    api/structmxml_1_1value__serializer_3_01T_01_4

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

* sphinx.ext.mathjax (9.0.1)
* 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)
* breathe (4.36.0)
* exhale (0.3.7)
* myst_parser (4.0.1)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/home/maarten/projects/mxml/py/lib/python3.13/site-packages/sphinx/domains/cpp/__init__.py", line 1115, in _resolve_xref_inner
        assert parent_symbol  # should be there
               ^^^^^^^^^^^^^
    AssertionError


The full traceback has been saved in:
/tmp/sphinx-err-08g3h3qt.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
ninja: build stopped: subcommand failed.

[jakobandersen]

I only have CMake 3.22, and if I change the requirement down to that, then I get an error, which may be related to the version downgrade(?):

CMake Error: The source directory "SOURCES/CMakeFiles/CMakeTmp" does not exist.
Specify --help for usage, or press the help button on the CMake GUI.
CMake Error at CMakeLists.txt:40 (try_compile):
  Failed to configure test project build system.

[mhekkel]

I only have CMake 3.22, and if I change the requirement down to that, then I get an error, which may be related to the version downgrade(?):

If you're asking this because you try to build mxml? Yes, it is related. You really need version 3.23 or higher.

You can download standalone executables of more recent versions of cmake from the cmake.org website.