Fix reference cycle in hf_raise_for_status causing delayed object destruction (#4092)

* Fix reference cycle in hf_raise_for_status by extending _format with **attrs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* simpler tests

* syntax

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Wauplin

src/huggingface_hub/utils/_http.py

@@ -774,26 +774,17 @@ def hf_raise_for_status(response: httpx.Response, endpoint_name: str | None = No
 
         if error_code == "RevisionNotFound":
             message = f"{response.status_code} Client Error." + "\n\n" + f"Revision Not Found for url: {response.url}."
-            revision_err = _format(RevisionNotFoundError, message, response)
-            revision_err.repo_type = repo_type
-            revision_err.repo_id = repo_id
-            raise revision_err from e
+            raise _format(RevisionNotFoundError, message, response, repo_type=repo_type, repo_id=repo_id) from e
 
         elif error_code == "EntryNotFound":
             message = f"{response.status_code} Client Error." + "\n\n" + f"Entry Not Found for url: {response.url}."
-            entry_err = _format(RemoteEntryNotFoundError, message, response)
-            entry_err.repo_type = repo_type
-            entry_err.repo_id = repo_id
-            raise entry_err from e
+            raise _format(RemoteEntryNotFoundError, message, response, repo_type=repo_type, repo_id=repo_id) from e
 
         elif error_code == "GatedRepo":
             message = (
                 f"{response.status_code} Client Error." + "\n\n" + f"Cannot access gated repo for url {response.url}."
             )
-            gated_err = _format(GatedRepoError, message, response)
-            gated_err.repo_type = repo_type
-            gated_err.repo_id = repo_id
-            raise gated_err from e
+            raise _format(GatedRepoError, message, response, repo_type=repo_type, repo_id=repo_id) from e
 
         elif error_message == "Access to this resource is disabled.":
             message = (
@@ -817,9 +808,9 @@ def hf_raise_for_status(response: httpx.Response, endpoint_name: str | None = No
                 + "\nPlease make sure you specified the correct bucket id (namespace/name)."
                 + "\nIf the bucket is private, make sure you are authenticated and your token has the required permissions."
             )
-            bucket_err = _format(BucketNotFoundError, message, response)
-            bucket_err.bucket_id = _parse_bucket_id_from_url(request_url)
-            raise bucket_err from e
+            raise _format(
+                BucketNotFoundError, message, response, bucket_id=_parse_bucket_id_from_url(request_url)
+            ) from e
 
         elif error_code == "RepoNotFound" or (
             response.status_code == 401
@@ -841,10 +832,7 @@ def hf_raise_for_status(response: httpx.Response, endpoint_name: str | None = No
                 " make sure you are authenticated and your token has the required permissions."
                 + "\nFor more details, see https://huggingface.co/docs/huggingface_hub/authentication"
             )
-            repo_err = _format(RepositoryNotFoundError, message, response)
-            repo_err.repo_type = repo_type
-            repo_err.repo_id = repo_id
-            raise repo_err from e
+            raise _format(RepositoryNotFoundError, message, response, repo_type=repo_type, repo_id=repo_id) from e
 
         elif response.status_code == 400:
             message = (
@@ -919,7 +907,9 @@ def _warn_on_warning_headers(response: httpx.Response) -> None:
 _HfHubHTTPErrorT = TypeVar("_HfHubHTTPErrorT", bound=HfHubHTTPError)
 
 
-def _format(error_type: type[_HfHubHTTPErrorT], custom_message: str, response: httpx.Response) -> _HfHubHTTPErrorT:
+def _format(
+    error_type: type[_HfHubHTTPErrorT], custom_message: str, response: httpx.Response, **attrs: Any
+) -> _HfHubHTTPErrorT:
     server_errors = []
 
     # Retrieve server error from header
@@ -1009,7 +999,10 @@ def _format(error_type: type[_HfHubHTTPErrorT], custom_message: str, response: h
             final_error_message += request_id_message
 
     # Return
-    return error_type(final_error_message.strip(), response=response, server_message=server_message or None)
+    err = error_type(final_error_message.strip(), response=response, server_message=server_message or None)
+    for k, v in attrs.items():
+        setattr(err, k, v)
+    return err
 
 
 def _curlify(request: httpx.Request) -> str:

tests/test_utils_http.py

@@ -1,6 +1,7 @@
 import threading
 import time
 import unittest
+import weakref
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from typing import Generator, Optional
 from unittest.mock import Mock, call, patch
@@ -702,3 +703,39 @@ def test_non_bucket_url(self):
 
     def test_http_url(self):
         assert _parse_bucket_id_from_url("http://localhost:8080/api/buckets/ns/name") == "ns/name"
+
+
+class TestNoReferenceCycleInRaise:
+    """Regression test: hf_raise_for_status must not create reference cycles.
+
+    See https://github.com/huggingface/huggingface_hub/pull/4084 for details.
+    When exceptions were stored in local variables before `raise ... from e`,
+    CPython reference cycles prevented deterministic cleanup, causing real
+    issues downstream (e.g. vLLM GPU memory not released).
+    """
+
+    def test_no_refcycle(self):
+        url = "https://huggingface.co/api/models/user/repo"
+        request = Mock(spec=httpx.Request)
+        request.url = httpx.URL(url)
+        response = Mock(spec=httpx.Response)
+        response.status_code = 404
+        response.url = url
+        response.headers = httpx.Headers({"X-Error-Code": "RepoNotFound"})
+        response.json.return_value = {}
+        response.request = request
+        response.raise_for_status.side_effect = httpx.HTTPStatusError("404", request=request, response=response)
+
+        ref = None
+        try:
+            hf_raise_for_status(response)
+        except RepositoryNotFoundError as exc:
+            # Clear the traceback to isolate our fix from the inherent
+            # except-block cycle (exc.__traceback__ -> this frame -> exc).
+            # We only care that hf_raise_for_status itself does not create a
+            # cycle via intermediate local variables.
+            exc.__traceback__ = None
+            ref = weakref.ref(exc)
+        # After exiting the except block, the exception should be freed by
+        # refcount alone (no gc.collect() needed) if there is no cycle.
+        assert ref() is None