github-starred/ollama
2
0
Fork 0
mirror of https://github.com/ollama/ollama.git synced 2026-05-07 16:40:08 -05:00
Code Issues 14.5k Packages Projects Releases 120 Wiki Activity

[PR #9022] [CLOSED] api: add optional hints to errors for troubleshooting #18106

New Issue
Closed
opened 2026-04-16 06:24:39 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-16 06:24:39 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/ollama/ollama/pull/9022
Author: @BruceMacD
Created: 2/11/2025
Status: ❌ Closed

Base: main ← Head: brucemacd/err-hint

📝 Commits (9)

📊 Changes

6 files changed (+344 additions, -40 deletions)

View changed files

📝 api/client.go (+31 -12)
📝 api/client_test.go (+273 -0)
📝 api/types.go (+16 -21)
📝 openai/openai.go (+3 -3)
📝 server/images.go (+7 -2)
📝 server/routes.go (+14 -2)

📄 Description

Introduce structured error responses that pair error messages with user-friendly troubleshooting hints. This improves error handling across the codebase and provides better guidance to users when things go wrong.

Key changes:

  • Add ErrorResponse type with Err and Hint fields
  • Update client to handle structured errors in streaming and regular responses
  • Add specific error handling for common cases like missing models
  • Improve CLI output to clearly show both errors and hints
  • Add comprehensive test coverage for new error formats

Maintains backward compatibility with existing error handling while making error messages more helpful and actionable for users.

When not ollama.com registry:
API response:

❯ curl http://localhost:11434/api/pull -d '{
  "model": "dne"
}' | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   215    0   195  100    20    616     63 --:--:-- --:--:-- --:--:--   680
{
  "status": "pulling manifest"
}
{
  "error": "pull model manifest: model not found: file does not exist",
  "hint": "Model \"dne:latest\" not found - please check the model name is correct and try again"
}

CLI output:

❯ ./ollama pull dne
pulling manifest 
Error:  pull model manifest: model not found: file does not exist

Model "dne:latest" not found - please check the model name is correct and try again

When ollama.com registry:
API response:

❯ curl http://localhost:11434/api/pull -d '{
  "model": "dne"
}' | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   215    0   195  100    20    616     63 --:--:-- --:--:-- --:--:--   680
{
  "status": "pulling manifest"
}
{
  "error": "pull model manifest: model not found: file does not exist",
  "hint": "Model \"dne\" not found - search available models at: https://ollama.com/search?q=dne"
}

CLI output:

❯ ./ollama pull dne
pulling manifest 
Error:  pull model manifest: model not found: file does not exist

Model "dne" not found - search available models at: https://ollama.com/search?q=dne

Follow-up:

  • We should add more hints to error cases as we encounter them. This starts will pull, which had a particularly bad error message.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/ollama/ollama/pull/9022 **Author:** [@BruceMacD](https://github.com/BruceMacD) **Created:** 2/11/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `brucemacd/err-hint` --- ### 📝 Commits (9) - [`00ba065`](https://github.com/ollama/ollama/commit/00ba065e90b35785067d8479dea054c4a54d9e11) api: document client stream behavior with a test - [`4d95681`](https://github.com/ollama/ollama/commit/4d9568172d5a7d4bd088946513dfd36e0185317d) api: add optional hints to errors for troubleshooting - [`99ab921`](https://github.com/ollama/ollama/commit/99ab9210ba8a271b2c43d6a65c63d7dd4f8e57ff) pr comments - [`6852546`](https://github.com/ollama/ollama/commit/68525466f28033b29f47f300bb09d2a401603b83) link hint to ollama.com - [`a5f2db3`](https://github.com/ollama/ollama/commit/a5f2db37449f14fd508d61973c930e5823669177) return hint in error function - [`32dd679`](https://github.com/ollama/ollama/commit/32dd67957df676233d54bff62cbdad9f4086c3f0) fix tests - [`2de8325`](https://github.com/ollama/ollama/commit/2de832552a01a974a36f78ccf5e8327f430d6854) use errors.Is - [`9bb5e3e`](https://github.com/ollama/ollama/commit/9bb5e3ee6929511d51bed32d7357c80db6cba0cd) Update api/types.go - [`b438a48`](https://github.com/ollama/ollama/commit/b438a483ba8d1ffbf72afda5a8db9c19822aa26d) gofmt ### 📊 Changes **6 files changed** (+344 additions, -40 deletions) <details> <summary>View changed files</summary> 📝 `api/client.go` (+31 -12) 📝 `api/client_test.go` (+273 -0) 📝 `api/types.go` (+16 -21) 📝 `openai/openai.go` (+3 -3) 📝 `server/images.go` (+7 -2) 📝 `server/routes.go` (+14 -2) </details> ### 📄 Description Introduce structured error responses that pair error messages with user-friendly troubleshooting hints. This improves error handling across the codebase and provides better guidance to users when things go wrong. Key changes: - Add ErrorResponse type with Err and Hint fields - Update client to handle structured errors in streaming and regular responses - Add specific error handling for common cases like missing models - Improve CLI output to clearly show both errors and hints - Add comprehensive test coverage for new error formats Maintains backward compatibility with existing error handling while making error messages more helpful and actionable for users. When not ollama.com registry: API response: ```shell ❯ curl http://localhost:11434/api/pull -d '{ "model": "dne" }' | jq % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 215 0 195 100 20 616 63 --:--:-- --:--:-- --:--:-- 680 { "status": "pulling manifest" } { "error": "pull model manifest: model not found: file does not exist", "hint": "Model \"dne:latest\" not found - please check the model name is correct and try again" } ``` CLI output: ```shell ❯ ./ollama pull dne pulling manifest Error: pull model manifest: model not found: file does not exist Model "dne:latest" not found - please check the model name is correct and try again ``` When ollama.com registry: API response: ```shell ❯ curl http://localhost:11434/api/pull -d '{ "model": "dne" }' | jq % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 215 0 195 100 20 616 63 --:--:-- --:--:-- --:--:-- 680 { "status": "pulling manifest" } { "error": "pull model manifest: model not found: file does not exist", "hint": "Model \"dne\" not found - search available models at: https://ollama.com/search?q=dne" } ``` CLI output: ```shell ❯ ./ollama pull dne pulling manifest Error: pull model manifest: model not found: file does not exist Model "dne" not found - search available models at: https://ollama.com/search?q=dne ``` Follow-up: - We should add more hints to error cases as we encounter them. This starts will pull, which had a particularly bad error message. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-04-16 06:24:39 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
amd
api
app
bug
build
cli
cloud
compatibility
context-length
create
docker
documentation
embeddings
feature request
feedback wanted
good first issue
gpt-oss
gpu
harmony
help wanted
image
install
intel
js
launch
linux
macos
memory
mlx
model
needs more info
networking
nvidia
ollama.com
performance
pull-request
Mirrored from GitHub Pull Request
 python
question
registry
rendering
thinking
tools
top
vulkan
windows
wsl
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/ollama#18106
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?