Improvements to UX when getting 404 errors from Hugging Face#2519
Improvements to UX when getting 404 errors from Hugging Face#2519miabbott wants to merge 6 commits intocontainers:mainfrom
Conversation
Previously all HTTP errors from the checksum API were caught and re-raised as a generic KeyError, losing the signal that the file simply does not exist on the server. Split the 404 case out into a FileNotFoundError carrying the URL, so callers can distinguish "file not found" from other transient or auth failures. Assisted-by: OpenCode 1.2.26 (Claude Sonnet 4.6) Signed-off-by: Micah Abbott <[email protected]>
Introduces a thin wrapper around the existing fetch_repo_files function that filters results to .gguf files only. This will be used to generate actionable suggestions when a user specifies a filename that does not exist in the repository. Assisted-by: OpenCode 1.2.26 (Claude Sonnet 4.6) Signed-off-by: Micah Abbott <[email protected]>
When HuggingfaceRepositoryModel.fetch_metadata encounters a FileNotFoundError (HTTP 404) for the requested file, fetch the list of GGUF files actually present in the repository and include them in the error message, so the user knows what to use instead. Assisted-by: OpenCode 1.2.26 (Claude Sonnet 4.6) Signed-off-by: Micah Abbott <[email protected]>
The CLI fallback path in pull() is only meaningful when the HTTP download fails due to a transient or auth error. A FileNotFoundError means the file does not exist at all; falling through to the CLI would never succeed and previously produced a completely misleading "huggingface cli download not available" error. Re-raise immediately with the original exception instead. Assisted-by: OpenCode 1.2.26 (Claude Sonnet 4.6) Signed-off-by: Micah Abbott <[email protected]>
The previous NotImplementedError said "huggingface cli download not available", implying the hf tool was missing. This method is a deliberate dead-end because the hf CLI does not support direct GGUF file downloads; update the message to reflect that accurately. Assisted-by: OpenCode 1.2.26 (Claude Sonnet 4.6) Signed-off-by: Micah Abbott <[email protected]>
Add test_huggingface_404_ux.py covering the five commits that improve the user experience when a 404 is returned by the HuggingFace registry: - fetch_checksum_from_api_base: verify 404 raises FileNotFoundError (not KeyError) and that the URL is included in the exception, while other HTTP errors and URLErrors still raise KeyError - fetch_gguf_files: verify it returns a sorted, filtered list of .gguf paths, returns an empty list on exceptions, and forwards the revision argument to fetch_repo_files - HuggingfaceRepositoryModel.fetch_metadata: verify the error message lists available GGUF files when present, falls back to a browse URL when none are found, and always re-raises FileNotFoundError - pull(): verify FileNotFoundError propagates immediately without invoking the CLI fallback, while other exceptions still attempt it - get_cli_download_args: verify NotImplementedError is raised with the updated message and that the old misleading text is absent Assisted-by: OpenCode 1.2.26 (Claude Sonnet 4.6) Signed-off-by: Micah Abbott <[email protected]>
miabbott
requested review from
bmahabirbu,
cgruver,
engelmi,
jhjaggars,
maxamillion,
mikebonnet,
olliewalsh,
rhatdan and
swarajpande5
as code owners
miabbott
temporarily deployed
to
macos-installer
GitHub Actions
Inactive
Reviewer's GuideImproves Hugging Face GGUF download UX by turning 404 checksum lookups into explicit FileNotFoundError, surfacing available GGUF files for the repo, preventing a misleading CLI fallback path, clarifying the CLI error message, and adding unit tests around the new behavior. File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the user experience when encountering 404 errors from Hugging Face repositories. Previously, such errors would lead to a generic "huggingface cli download not available" message. The changes now provide specific feedback, indicating if a requested GGUF file is not found and listing other available GGUF files within the repository, or suggesting a browse URL if no GGUF files are present. This prevents misleading error messages and guides users more effectively. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- In
fetch_gguf_filesyou catch a bareExceptionand silently return an empty list; consider narrowing this to a more specific set of network/HTTP errors or at least logging/debugging the failure so that genuine programmer errors (e.g., bad response shape) don’t get masked as “no files found.”
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `fetch_gguf_files` you catch a bare `Exception` and silently return an empty list; consider narrowing this to a more specific set of network/HTTP errors or at least logging/debugging the failure so that genuine programmer errors (e.g., bad response shape) don’t get masked as “no files found.”Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly improves the user experience when encountering 404 errors from Hugging Face by providing a much clearer error message, including a list of available files. The changes are well-implemented, with specific error handling for 404s and logic to prevent misleading fallback errors. The addition of comprehensive unit tests ensures the new functionality is robust. I have one suggestion to improve the robustness of the new helper function.
| except Exception: | ||
| return [] |
There was a problem hiding this comment.
Catching a broad Exception and silently returning can hide underlying issues, such as an AttributeError if the API returns an unexpected format for a file path. This makes debugging more difficult.
It would be more robust to log the exception to aid in debugging. Since this function is for enhancing an error message, swallowing the error is acceptable, but logging it is highly recommended.
For example:
except Exception as e:
logger.debug(f"Could not fetch GGUF file list for '{repo_name}': {e}")
return []
There was a problem hiding this comment.
This looks like a reasonable concern.
| # The file does not exist on the server; the CLI fallback cannot | ||
| # help here, and falling through would produce a misleading error. | ||
| raise | ||
| except Exception as e: |
There was a problem hiding this comment.
The fix for the 404 handling is to just remove this block, it existed as a fallback to handle pulling safetensors models until it was implemented. Since #2224 it should be ok to remove it, but we would need to test a number of scenarios first to be sure it's safe to do.
| self.model_hash = f"sha256:{fetch_checksum_from_api(self.organization, self.name)}" | ||
| try: | ||
| self.model_hash = f"sha256:{fetch_checksum_from_api(self.organization, self.name)}" | ||
| except FileNotFoundError: |
There was a problem hiding this comment.
Users would typically specific the Hugging Face model in <org>/<name>:<quant> format e.g hf://bartowski/gemma-2-9b-it-GGUF:Q4_K_M.
If the organisation name or the repo name are incorrect then will get a 404 here.
It looks like the intention here is to then list the available ggufs, but that doesn't make sense - either the org or the repo name is incorrect so it wouldn't be possible to list the available ggufs (could list the available repos for the org if there is an API for this but that would be huge in some cases, thousands for bartowski!).
I think it would be better to just raise an issue for all this to discuss. It is not a good first issue for a new contributor.
There was a problem hiding this comment.
Thanks for the feedback! We can discuss in #2524
|
A friendly reminder that this PR had no activity for 30 days. |
3 participants
I tried running some models from HF using
ramalamaand was encountering errors about the HF CLI not being installed. I knew this was incorrect, so I fed the debug output from my attempts to OpenCode + Sonnet 4.6 to diagnose the error and suggest changes.It found that when HF returned 404 errors, the errors were not properly caught and raised the generic message about the missing CLI.
This PR improves the error handling when a 404 response is received from HF and will report back to the user any valid GGUF files that can be fetched for the repository.
Previous to this PR:
After this PR:
Summary by Sourcery
Improve Hugging Face transport error handling for missing GGUF files to provide clearer feedback and avoid misleading CLI fallback errors.
Bug Fixes:
Enhancements:
Tests: