Describe the bug
sphinx-build used to suppress python backtraces when an extension threw an ExtensionError. This allows the extension to report e.g. syntax errors in input files to the user in a user-friendly way. (QEMU has some extensions that do this: we might for instance report that the user made a syntax error in a file that the extension reads, including the filename and line number of that file.) Recent versions of sphinx-build seem to have regressed here, and now print a big long message implying that the user should report a bug in Sphinx.
Similarly, if a conf.py raises ConfigError a big message is printed. The reason ConfigError was introduced was to allow conf.py files to report problems in a friendly way without Sphinx putting in a confusing extra message implying that there's a bug (see issue #7108).
I think that when an extension throws ExtensionError, or a conf.py throws ConfigError:
- sphinx should not print any of this extra information about versions or loaded extensions
- sphinx should not save a traceback to a temp file
- even when -T is passed on the command line, it should not print the python traceback
- this should be the case whether using '-j auto' for parallelism or not
This allows config files and extensions to report issues to the user with the formatting and detail that they consider appropriate, and in a way that doesn't make the user believe that there's a Sphinx or extension bug involved.
Compare, for a simple extension that always throws ExtensionError from its run() method:
$ sphinx-build --version
sphinx-build 7.2.6
$ sphinx-build docs out
Running Sphinx v7.2.6
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
Extension error:
This is an expected error from TestExtn
with
$ sphinx-build --version
sphinx-build 9.1.0
$ sphinx-build docs out
Running Sphinx v9.1.0
loading translations [en]... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
Extension error!
Versions
========
* Platform: linux; (Linux-6.17.0-1024-oem-x86_64-with-glibc2.39)
* Python version: 3.12.3 (CPython)
* Sphinx version: 9.1.0
* Docutils version: 0.22.4
* Jinja2 version: 3.1.6
* Pygments version: 2.20.0
Last Messages
=============
writing output...
building [html]: targets for 1 source files that are out of date
updating environment:
[new config]
1 added, 0 changed, 0 removed
reading sources... [100%]
index
Loaded Extensions
=================
* sphinx.ext.mathjax (9.1.0)
* 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)
* test_extn (1.0)
Traceback
=========
File "/home/pm215/sphinx-bug/docs/extn/test_extn.py", line 13, in run
raise ExtensionError('This is an expected error from TestExtn')
sphinx.errors.ExtensionError: This is an expected error from TestExtn
The full traceback has been saved in:
/tmp/sphinx-err-vr3zyjtx.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.
And for ConfigError:
lanath:noble:sphinx-bug$ sphinx-build docs out
Running Sphinx v7.2.6
Configuration error:
problem in config
versus:
$ sphinx-build docs out
Running Sphinx v9.1.0
Configuration error!
Versions
========
* Platform: linux; (Linux-6.17.0-1024-oem-x86_64-with-glibc2.39)
* Python version: 3.12.3 (CPython)
* Sphinx version: 9.1.0
* Docutils version: 0.22.4
* Jinja2 version: 3.1.6
* Pygments version: 2.20.0
Last Messages
=============
None.
Loaded Extensions
=================
None.
Traceback
=========
File "/home/pm215/sphinx-bug/docs/conf.py", line 11, in <module>
raise ConfigError("problem in config")
sphinx.errors.ConfigError: problem in config
The full traceback has been saved in:
/tmp/sphinx-err-nx1lf1cp.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.
How to Reproduce
Simple repro, with three files:
1: docs/conf.py:
# Minimal config file
import sys
from pathlib import Path
from sphinx.errors import ConfigError
sys.path.append(str(Path('extn').resolve()))
extensions = [ 'test_extn' ]
2: docs/index.rst:
Test document: invoke the test extension.
.. test_extn::
3: docs/extn/test_extn.py:
# Test extension that always throws an ExtensionError
import sphinx
from docutils.parsers.rst import directives, Directive
from sphinx.errors import ExtensionError
class TestExtnDirective(Directive):
"""This extension always throws an error"""
required_argument = 0
optional_arguments = 0
has_content = False
def run(self):
raise ExtensionError('This is an expected error from TestExtn')
def setup(app):
""" Register test_extn directive with Sphinx"""
app.add_directive('test_extn', TestExtnDirective)
return dict(
version = '1.0',
parallel_read_safe = True,
parallel_write_safe = True
)
Run with:
To test the ConfigError variant, add this line to the end of conf.py:
raise ConfigError("problem in config")
Environment Information
Platform: linux; (Linux-6.17.0-1024-oem-x86_64-with-glibc2.39)
Python version: 3.12.3 (main, Jun 19 2026, 12:46:00) [GCC 13.3.0])
Python implementation: CPython
Sphinx version: 9.1.0
Docutils version: 0.22.4
Jinja2 version: 3.1.6
Pygments version: 2.20.0
Sphinx extensions
Additional context
No response
Describe the bug
sphinx-build used to suppress python backtraces when an extension threw an ExtensionError. This allows the extension to report e.g. syntax errors in input files to the user in a user-friendly way. (QEMU has some extensions that do this: we might for instance report that the user made a syntax error in a file that the extension reads, including the filename and line number of that file.) Recent versions of sphinx-build seem to have regressed here, and now print a big long message implying that the user should report a bug in Sphinx.
Similarly, if a conf.py raises ConfigError a big message is printed. The reason ConfigError was introduced was to allow conf.py files to report problems in a friendly way without Sphinx putting in a confusing extra message implying that there's a bug (see issue #7108).
I think that when an extension throws ExtensionError, or a conf.py throws ConfigError:
This allows config files and extensions to report issues to the user with the formatting and detail that they consider appropriate, and in a way that doesn't make the user believe that there's a Sphinx or extension bug involved.
Compare, for a simple extension that always throws ExtensionError from its run() method:
with
And for ConfigError:
versus:
How to Reproduce
Simple repro, with three files:
1:
docs/conf.py:2:
docs/index.rst:3:
docs/extn/test_extn.py:Run with:
To test the ConfigError variant, add this line to the end of conf.py:
Environment Information
Sphinx extensions
Additional context
No response