graphviz errors are reported only once and obsolete graphs are left behind

[marc-hb]

Describe the bug

Error handling is generally not tested in the software industry and sphinx.ext.graphviz is no exception :-(

When graphviz' dot tool fails to generate a diagram embedded with .. graphviz :: due to some error in the embedded diagram source code, the error is reported only once. If you invoke sphinx-build again then the error disappears. That's because the foo.html output file does not care about graphviz errors and is generated "incomplete" (i.e.: pointing to a missing .png file) anyway. So, the source foo.rst file is not processed again because it's output is already present and deemed OK.

Obvious fix 1: stop ignoring graphviz failures and don't generate incomplete .html output. Or generate it in some non-final location to help with debugging but don't put it in the final location.

To make things much worse, sphinx.ext.graphviz never deletes old html/_images/graphviz-e8ab96ded74ad33e0d9517bcb46629283b059273.png files. So, if you had successfully built an older and working version of the embedded .. graphviz :: diagram in the past and then you make a graphviz mistake, then you will get the last successful version of the .png file instead of a blank one. This makes it even more likely to miss errors: a missing diagram is relatively easy to notice while an older version is much easier to miss.

Obvious fix 2: before trying to generate any new .png file (or any generated file anywhere really), start by deleting all the obsolete ones with the same filenames.

How to Reproduce

conf.py

extensions = [
     "sphinx.ext.graphviz",
]

index.rst

This is a graphiz test
######################

.. graphviz::
   :caption: Flat state machine diagram1

   digraph smf_flat {
      node [style=rounded SYNTAX_ERROR=<<<<];
      init [shape = point];
      STATE_S0 [shape = box];
      STATE_S1 [shape = box];
      STATE_S2 [shape = box];

      init -> STATE_S0;
      STATE_S0 -> STATE_S1;
      STATE_S1 -> STATE_S2;
      STATE_S2 -> STATE_S0;
   }

Environment Information

Platform:              linux; (Linux-6.19.9-200.fc43.x86_64-x86_64-with-glibc2.42)
Python version:        3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)])
Python implementation: CPython
Sphinx version:        9.1.0
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.1

Sphinx extensions

`sphinx.ext.graphviz`

Additional context

This was originally found and described in

• doc: Graphiz warnings invisible, Graphiz errors downgraded and reported only once zephyrproject-rtos/zephyr#99932

[marc-hb]

The obvious workaround is "make clean" but you obviously do not want to do that when dealing with large and very time-consuming builds like in zephyrproject-rtos/zephyr#99932.

Fortunately, there is a very fast and not too inconvenient workaround: refresh the timestamp of all relevant source files. Either "save" from your editor or with something like touch $(git diff --name-only) or git grep --name-only 'graphviz' '*.rst' or touch $(git grep --name-only 'graphviz' '**.rst)

rm build/images/graphviz-* can also help.

[marc-hb]

Paying more attention to the outputs, I suspect sphinx.ext.graphviz might downgrade dot errors to warnings. Compare:

dot t.dot -o _ ; echo $?
Error: t.dot: syntax error in line 11 near ';'
1

... with:

sphinx-build
WARNING: dot code 'digraph smf_flat {\n   node [style=rounded SYNTAX_ERROR=<<<<];\n...
...
...

Such a downgrade would make no sense in this case considering the dot output is entirely missing.

Following the same logic, maybe sphinx.ext.graphviz also downgrades warnings to nothing at all which would "explain" #14362 ?