diff --git a/requirements-optional.txt b/requirements-optional.txt
index c20cfb398d6..4ddfc538114 100644
--- a/requirements-optional.txt
+++ b/requirements-optional.txt
@@ -7,6 +7,9 @@ ruff==0.13.3
 # For generating documentation.
 sphinx==8.2.3
 sphinx-autoapi==3.6.0
+# Pin to <4 due to breaking changes in 4.0.0 incompatible with sphinx-autoapi
+# https://github.com/readthedocs/sphinx-autoapi/issues/536
+astroid<4.0.0
 
 # For 'manage' interactive shell
 manage==0.1.15