linkcheck: retry HTTP timeouts when using linkcheck_retries

Apply linkcheck_retries to transient timeouts when linkcheck_report_timeouts_as_broken is false (default). The outer retry loop previously only continued on BROKEN, so TIMEOUT was returned immediately and extra retries were never used (fixes #14339).

Add regression coverage using a closure counter for request counting (Ruff B010; avoids setattr/dynamic attrs on TCPServer).

- sphinx/builders/linkcheck.py
- tests/test_builders/test_build_linkcheck.py
- CHANGES.rst

Made-with: Cursor

Author: root

CHANGES.rst

@@ -1,3 +1,12 @@
+Release in development
+======================
+
+Bugs fixed
+----------
+
+* #14339: linkcheck: Apply :confval:`linkcheck_retries` to HTTP timeouts when
+  :confval:`linkcheck_report_timeouts_as_broken` is false (default).
+
 Release 9.1.0 (released Dec 31, 2025)
 =====================================
 

sphinx/builders/linkcheck.py

@@ -478,12 +478,18 @@ def _check(self, docname: str, uri: str, hyperlink: Hyperlink) -> _URIProperties
             return _Status.BROKEN, '', 0
 
         # need to actually check the URI
-        status: _Status
         status, info, code = _Status.UNKNOWN, '', 0
-        for _ in range(self.retries):
+        for attempt in range(self.retries):
             status, info, code = self._check_uri(uri, hyperlink)
-            if status != _Status.BROKEN:
+            if attempt + 1 >= self.retries:
                 break
+            # ``linkcheck_retries`` applies to broken links; also retry transient
+            # timeouts when they are reported as such (not when folded into "broken").
+            if status == _Status.BROKEN:
+                continue
+            if status == _Status.TIMEOUT and self._timeout_status == _Status.TIMEOUT:
+                continue
+            break
 
         return status, info, code
 

tests/test_builders/test_build_linkcheck.py

@@ -1257,6 +1257,49 @@ def do_GET(self) -> None:
     assert content['status'] == 'timeout'
 
 
+@pytest.mark.sphinx(
+    'linkcheck',
+    testroot='linkcheck-localserver',
+    freshenv=True,
+    confoverrides={
+        'linkcheck_report_timeouts_as_broken': False,
+        'linkcheck_timeout': 0.05,
+        'linkcheck_retries': 3,
+    },
+)
+def test_retries_after_transient_timeout(app: SphinxTestApp) -> None:
+    """linkcheck_retries must retry when the server is slow (issue #14339)."""
+    get_n = [0]
+
+    class SlowThenFastHandler(BaseHTTPRequestHandler):
+        protocol_version = 'HTTP/1.1'
+
+        def do_HEAD(self) -> None:
+            # Force a GET so each attempt measures response latency from do_GET.
+            self.send_response(405, 'Method Not Allowed')
+            self.send_header('Content-Length', '0')
+            self.end_headers()
+
+        def do_GET(self) -> None:
+            get_n[0] += 1
+            count = get_n[0]
+            if count <= 2:
+                time.sleep(0.15)
+            content = b'ok\n'
+            self.send_response(200, 'OK')
+            self.send_header('Content-Length', str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+
+    with serve_application(app, SlowThenFastHandler):
+        app.build()
+
+    with open(app.outdir / 'output.json', encoding='utf-8') as fp:
+        content = json.load(fp)
+
+    assert content['status'] == 'working'
+
+
 @pytest.mark.sphinx(
     'linkcheck',
     testroot='linkcheck-localserver',