implement retry mechanism for HEAD call

Author: hanouticelina

docs/source/en/package_reference/environment_variables.md

@@ -73,7 +73,11 @@ For more details, see [logging reference](../package_reference/utilities#hugging
 
 ### HF_HUB_ETAG_TIMEOUT
 
-Integer value to define the number of seconds to wait for server response when fetching the latest metadata from a repo before downloading a file. If the request times out, `huggingface_hub` will default to the locally cached files. Setting a lower value speeds up the workflow for machines with a slow connection that have already cached files. A higher value guarantees the metadata call to succeed in more cases. Default to 10s.
+Integer value to define the initial number of seconds to wait for server response when fetching the latest metadata from a repo before downloading a file. If the request times out, `huggingface_hub` will default to the locally cached files. If no cached file is found, a retry is attempted with a longer timeout (see `HF_HUB_ETAG_TIMEOUT_RETRY`). Setting a lower value speeds up the workflow for machines with a slow connection that have already cached files. Default to 10s.
+
+### HF_HUB_ETAG_TIMEOUT_RETRY
+
+Integer value to define the number of seconds to wait when retrying metadata fetch after an initial timeout. When the initial metadata request times out and no local cached file is found, `huggingface_hub` will retry with this longer timeout before failing. This helps handle transient network slowdowns while keeping the initial timeout fast for cached files. Default to 60s.
 
 ### HF_HUB_DOWNLOAD_TIMEOUT
 

src/huggingface_hub/constants.py

@@ -32,6 +32,7 @@ def _as_int(value: Optional[str]) -> Optional[int]:
 CONFIG_NAME = "config.json"
 REPOCARD_NAME = "README.md"
 DEFAULT_ETAG_TIMEOUT = 10
+DEFAULT_ETAG_TIMEOUT_RETRY = 60
 DEFAULT_DOWNLOAD_TIMEOUT = 10
 DEFAULT_REQUEST_TIMEOUT = 10
 DOWNLOAD_CHUNK_SIZE = 10 * 1024 * 1024
@@ -230,6 +231,9 @@ def _as_int(value: Optional[str]) -> Optional[int]:
 # Used to override the etag timeout on a system level
 HF_HUB_ETAG_TIMEOUT: int = _as_int(os.environ.get("HF_HUB_ETAG_TIMEOUT")) or DEFAULT_ETAG_TIMEOUT
 
+# Used to override the etag retry timeout on a system level (for retrying after initial timeout when no local file)
+HF_HUB_ETAG_TIMEOUT_RETRY: int = _as_int(os.environ.get("HF_HUB_ETAG_TIMEOUT_RETRY")) or DEFAULT_ETAG_TIMEOUT_RETRY
+
 # Used to override the get request timeout on a system level
 HF_HUB_DOWNLOAD_TIMEOUT: int = _as_int(os.environ.get("HF_HUB_DOWNLOAD_TIMEOUT")) or DEFAULT_DOWNLOAD_TIMEOUT
 

src/huggingface_hub/file_download.py

@@ -1131,8 +1131,28 @@ def _hf_hub_download_to_cache_dir(
                     if not force_download:
                         return pointer_path
 
-        # Otherwise, raise appropriate error
-        _raise_on_head_call_error(head_call_error, force_download, local_files_only)
+            # No local file found, retry with longer timeout if it was a timeout error
+            if isinstance(head_call_error, httpx.TimeoutException):
+                logger.info("Metadata fetch timed out and no local file found. Retrying with longer timeout..")
+                (url_to_download, etag, commit_hash, expected_size, xet_file_data, head_call_error) = (
+                    _get_metadata_or_catch_error(
+                        repo_id=repo_id,
+                        filename=filename,
+                        repo_type=repo_type,
+                        revision=revision,
+                        endpoint=endpoint,
+                        etag_timeout=constants.HF_HUB_ETAG_TIMEOUT_RETRY,
+                        headers=headers,
+                        token=token,
+                        local_files_only=local_files_only,
+                        storage_folder=storage_folder,
+                        relative_filename=relative_filename,
+                    )
+                )
+
+        # If still error, raise
+        if head_call_error is not None:
+            _raise_on_head_call_error(head_call_error, force_download, local_files_only)
 
     # From now on, etag, commit_hash, url and size are not None.
     assert etag is not None, "etag must have been retrieved from server"
@@ -1300,9 +1320,26 @@ def _hf_hub_download_to_local_dir(
                 )
             if not force_download:
                 return local_path
+        elif not force_download and isinstance(head_call_error, httpx.TimeoutException):
+            # No local file found, retry with longer timeout if it was a timeout error
+            logger.info("Metadata fetch timed out and no local file found. Retrying with longer timeout...")
+            (url_to_download, etag, commit_hash, expected_size, xet_file_data, head_call_error) = (
+                _get_metadata_or_catch_error(
+                    repo_id=repo_id,
+                    filename=filename,
+                    repo_type=repo_type,
+                    revision=revision,
+                    endpoint=endpoint,
+                    etag_timeout=constants.HF_HUB_ETAG_TIMEOUT_RETRY,
+                    headers=headers,
+                    token=token,
+                    local_files_only=local_files_only,
+                )
+            )
 
-        # Otherwise => raise
-        _raise_on_head_call_error(head_call_error, force_download, local_files_only)
+        # If still error, raise
+        if head_call_error is not None:
+            _raise_on_head_call_error(head_call_error, force_download, local_files_only)
 
     # From now on, etag, commit_hash, url and size are not None.
     assert etag is not None, "etag must have been retrieved from server"