sphinx autodoc "ValueError: invalid signature"
Fixes Sphinx autodoc crashing on functions whose signatures it cannot parse. The skill shows how to find the offending callable, simplify or guard its signature, and confirm autodoc renders the page. It covers decorators, C extensions, and dynamically generated functions.
TL;DR
Find the callable named just before the traceback, then give autodoc a parseable signature. Unwrap or annotate the decorator, add an explicit signature, or exclude the member. Rebuild and confirm the page renders.
The exact error
ValueError: invalid signatureSteps
Identify the callable Read the traceback above the ValueError; autodoc names the module and object it was processing when it failed. Success check: You have the module path and object name of the failing callable.
Inspect the signature Import the object in a Python shell and call inspect.signature on it. Decorators that hide wrapped and C functions without _textsignature__ are the usual culprits. Success check: inspect.signature raises the same ValueError, confirming the source.
Give it a parseable signature For decorated functions, set functools.wraps or assign wrapped. For dynamic callables, attach an explicit signature object. As a last resort, exclude the member with :exclude-members:. Success check: inspect.signature returns a valid signature and the object imports cleanly.
Rebuild the affected page Run sphinx-build -b html on the project and open the rendered API page. Success check: The page renders with the correct parameter list and the build log shows no ValueError.
When to use
- Use when autodoc dies on ValueError: invalid signature during a docs build.
- Use when an agent generates API reference for a codebase with heavy decorators or C extensions.
When not to use
- Not for ImportError or ModuleNotFoundError in autodoc (different failure family).
- Not for signature mismatches between docs and code (that is doc drift, not a build crash).
Why it happens
Autodoc calls inspect.signature on every documented callable. Objects whose signatures are constructed dynamically, hidden by decorators without wrapped, or implemented in C without signature metadata make that call raise ValueError, which aborts the page.
Edge cases
napoleon and autodoc-typehints change how signatures are processed, so a signature that builds under plain autodoc can fail with extensions enabled. Mocking the module with autodocmockimports can hide the real signature; prefer fixing the signature over mocking when the object is importable.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_BROodA3W42dXhQCcqGIjFw