Improve whoami() error messages by specifying token source

src/huggingface_hub/hf_api.py

@@ -1615,46 +1615,133 @@ def run_as_future(self, fn: Callable[..., R], *args, **kwargs) -> Future[R]:
         self._thread_pool
         return self._thread_pool.submit(fn, *args, **kwargs)
 
+
+    from huggingface_hub.utils._auth import _get_token_from_google_colab, _get_token_from_environment, _get_token_from_file
+
+    def _get_token_source(self, token: Optional[Union[bool, str]] = None) -> str:
+        """
+        Determine the source of the token being used.
+
+        Args:
+            token: The token parameter passed to whoami
+
+        Returns:
+            str: Source of the token ("parameter", "environment", "file", "colab", or "unknown")
+        """
+        if isinstance(token, str):
+            return "parameter"
+
+        # Use the helper functions to check token sources
+        if _get_token_from_environment():
+            return "environment"
+
+        if _get_token_from_file():
+            return "file"
+
+        if _get_token_from_google_colab():
+            return "colab"
+
+        return "unknown"
+
+    def _get_token_error_message(self, source: str) -> str:
+        """
+        Generate a detailed error message based on the token source.
+
+        Args:
+            source: The source of the token ("parameter", "environment", "file", "colab", or "unknown")
+
+        Returns:
+            str: Customized error message
+        """
+        base_message = "Invalid user token. "
+
+        if source == "parameter":
+            return base_message + (
+                "The token you provided as parameter is invalid. Please verify it's correct "
+                "or remove it to use the default authentication method."
+            )
+        elif source == "environment":
+            return base_message + (
+                "The token from HF_TOKEN environment variable is invalid. "
+                "Note that HF_TOKEN takes precedence over the token file. "
+                "Either update HF_TOKEN or unset it to use the token from `huggingface-cli login`."
+            )
+        elif source == "file":
+            return base_message + (
+                "The token stored in ~/.cache/huggingface/token is invalid. "
+                "Please run `huggingface-cli login` to update it."
+            )
+        elif source == "colab":
+            return base_message + (
+                "The token from Google Colab vault is invalid. "
+                "Please run `huggingface-cli login` in your Colab notebook to update it."
+            )
+        else:
+            return base_message + (
+                "Please make sure you are properly logged in by executing `huggingface-cli login`, "
+                "or provide a valid token."
+            )
+
+
     @validate_hf_hub_args
     def whoami(self, token: Union[bool, str, None] = None) -> Dict:
         """
         Call HF API to know "whoami".
-
+        
         Args:
             token (Union[bool, str, None], optional):
                 A valid user access token (string). Defaults to the locally saved
                 token, which is the recommended method for authentication (see
                 https://huggingface.co/docs/huggingface_hub/quick-start#authentication).
                 To disable authentication, pass `False`.
         """
+        # Get the effective token using the helper function get_token
+        effective_token = get_token(token or self.token or True)
+
         r = get_session().get(
             f"{self.endpoint}/api/whoami-v2",
-            headers=self._build_hf_headers(
-                # If `token` is provided and not `None`, it will be used by default.
-                # Otherwise, the token must be retrieved from cache or env variable.
-                token=(token or self.token or True),
-            ),
+            headers=self._build_hf_headers(token=effective_token),
         )
+
         try:
             hf_raise_for_status(r)
         except HTTPError as e:
-            raise HTTPError(
-                "Invalid user token. If you didn't pass a user token, make sure you "
-                "are properly logged in by executing `huggingface-cli login`, and "
-                "if you did pass a user token, double-check it's correct.",
-                request=e.request,
-                response=e.response,
-            ) from e
-        return r.json()
+            error_message = "Invalid user token."
 
+            # Check which token is the effective one and generate the error message accordingly
+            if effective_token == _get_token_from_google_colab():
+                error_message += (
+                    " The token from Google Colab vault is invalid. "
+                    "Please run `huggingface-cli login` in your Colab notebook to update it."
+                )
+            elif effective_token == _get_token_from_environment():
+                error_message += (
+                    " The token from HF_TOKEN environment variable is invalid. "
+                    "Note that HF_TOKEN takes precedence over the token file. "
+                    "Either update HF_TOKEN or unset it to use the token from `huggingface-cli login`."
+                )
+            elif effective_token == _get_token_from_file():
+                error_message += (
+                    " The token stored in ~/.cache/huggingface/token is invalid. "
+                    "Please run `huggingface-cli login` to update it."
+                )
+            else:
+                error_message += (
+                    " Please make sure you are properly logged in by executing `huggingface-cli login`, "
+                    "or provide a valid token."
+                )
+
+            raise HTTPError(error_message, request=e.request, response=e.response) from e
+
+        return r.json()
     @_deprecate_method(
         version="1.0",
         message=(
             "Permissions are more complex than when `get_token_permission` was first introduced. "
             "OAuth and fine-grain tokens allows for more detailed permissions. "
             "If you need to know the permissions associated with a token, please use `whoami` and check the `'auth'` key."
         ),
-    )
+    )    
     def get_token_permission(
         self, token: Union[bool, str, None] = None
     ) -> Literal["read", "write", "fineGrained", None]: