ollama

Postconditions — what we check

• chat · chat-no-try-catch

  error
  Whenawaited ollama.chat() call is not wrapped in try/catch
  ThrowsError
  Required handlingCaller MUST wrap ollama.chat() in try/catch. The Ollama server runs locally and connection refused errors (ECONNREFUSED) are common when the server is not running. Model-not-found errors also throw. The error object has .status / .statusCode (HTTP status) and .message properties.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• generate · generate-no-try-catch

  error
  Whenawaited ollama.generate() call is not wrapped in try/catch
  ThrowsError
  Required handlingCaller MUST wrap ollama.generate() in try/catch. Connection refused, model not found, and network errors all throw an unhandled Error. This is particularly dangerous in AI pipelines where silent failure breaks the entire workflow without visible user feedback.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• embed · embed-no-try-catch

  error
  Whenawaited ollama.embed() call is not wrapped in try/catch
  ThrowsError
  Required handlingCaller MUST wrap ollama.embed() in try/catch. Embedding generation makes an HTTP request to the Ollama server. Server unavailability or invalid model name throws an uncaught Error that silently breaks RAG pipelines.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[1][2]
• pull · pull-no-try-catch

  error
  Whenawaited ollama.pull() call is not wrapped in try/catch
  ThrowsResponseError
  Required handlingCaller MUST wrap ollama.pull() in try/catch. The call makes an HTTP request to the Ollama server (local or remote). Common failure modes: ECONNREFUSED when the Ollama server is not running, ResponseError with status_code 404 when the model name does not exist in the registry, and network errors during large model downloads. The ResponseError has .error (message string) and .status_code (HTTP integer) properties. In streaming mode, an AbortError is thrown if abort() is called mid-download.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4][5]
• pull · pull-model-not-found

  error
  Whenollama.pull() called with a model name that does not exist in the registry
  ThrowsResponseError
  Required handlingResponseError with status_code 404 is thrown when the model name is invalid or does not exist in the Ollama registry. Callers that pull models dynamically based on user input or configuration must handle 404 separately from network errors. Checking error.status_code === 404 distinguishes "model name typo" from "server unavailable" (ECONNREFUSED does not have a status_code property).
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[4]
• create · create-no-try-catch

  error
  Whenawaited ollama.create() call is not wrapped in try/catch
  ThrowsResponseError | Error
  Required handlingCaller MUST wrap ollama.create() in try/catch. Two distinct error types: (1) Error("Creating with a local path is not currently supported from ollama-js") — thrown immediately when request.from is a local filesystem path (starts with '.' or '/'); (2) ResponseError — thrown when the base model named in request.from does not exist on the server (404), server error during creation (500), or ECONNREFUSED. The local-path error is thrown synchronously before any network call.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[6][3]
• create · create-local-path-unsupported

  error
  Whenollama.create() called with request.from pointing to a local filesystem path
  ThrowsError
  Required handlingThe Node.js ollama-js client throws Error("Creating with a local path is not currently supported from ollama-js") synchronously when request.from is a local file path. This is a known SDK limitation (GitHub issue #191). Applications that allow user-provided model sources must validate that the path is a registry name (e.g. 'llama3.2') not a filesystem path before calling create(). This error is thrown before any HTTP request is made and will not have a status_code property.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[6]
• show · show-no-try-catch

  error
  Whenawaited ollama.show() call is not wrapped in try/catch
  ThrowsResponseError
  Required handlingCaller MUST wrap ollama.show() in try/catch. ResponseError with status_code 404 is thrown when the model does not exist on the server. This is a common silent failure in model selection flows: code checks show() to determine model capabilities, swallows the 404, and then proceeds to use a model that doesn't exist. The pattern "check capabilities with show() then call chat()" must handle both 404 from show() and ECONNREFUSED from chat().
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[3][4]
• delete · delete-no-try-catch

  warning
  Whenawaited ollama.delete() call is not wrapped in try/catch
  ThrowsResponseError
  Required handlingCaller MUST wrap ollama.delete() in try/catch. ResponseError with status_code 404 is thrown when the model name does not exist on the server. This is particularly common in idempotent cleanup flows where code tries to delete a model that may already have been removed. Applications that manage model lifecycle must distinguish 404 (already gone, often acceptable) from ECONNREFUSED (server down, critical error).
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[3][4]
• copy · copy-no-try-catch

  warning
  Whenawaited ollama.copy() call is not wrapped in try/catch
  ThrowsResponseError
  Required handlingCaller MUST wrap ollama.copy() in try/catch. ResponseError with status_code 404 is thrown when the source model (request.source) does not exist. The error message from the Ollama server describes which model was not found. Model versioning flows that copy models must handle source-not-found as a distinct error from server unavailability.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[3][4]
• webSearch · websearch-no-try-catch

  error
  Whenawaited ollama.webSearch() call is not wrapped in try/catch
  ThrowsResponseError | Error
  Required handlingCaller MUST wrap ollama.webSearch() in try/catch. Two distinct error scenarios: (1) Error("Query is required") thrown synchronously when request.query is empty or missing — happens before any network call; (2) ResponseError with status_code 401 when OLLAMA_API_KEY is not set or the API key is invalid/expired. Unlike other ollama methods, webSearch() calls the external ollama.com cloud API, not the local Ollama server, so ECONNREFUSED errors indicate ollama.com connectivity issues, not local server status. Agentic tool workflows that use webSearch as a tool must handle auth failures distinctly from query validation errors.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[3][4][5]
• webSearch · websearch-missing-api-key

  error
  Whenollama.webSearch() called without OLLAMA_API_KEY environment variable set
  ThrowsResponseError
  Required handlingResponseError with status_code 401 is thrown when OLLAMA_API_KEY is not configured. The ollama-js client automatically injects the key as a Bearer token for requests to ollama.com, but if the env var is absent, the request proceeds unauthenticated and the cloud API rejects it. Applications that use webSearch in production must validate OLLAMA_API_KEY is present at startup, not at first call. Agent systems that register webSearch as a tool must expose an actionable error message rather than letting the 401 surface as an unhandled exception.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilitysilent
  Sources[3][4]
• webFetch · webfetch-no-try-catch

  error
  Whenawaited ollama.webFetch() call is not wrapped in try/catch
  ThrowsResponseError | Error
  Required handlingCaller MUST wrap ollama.webFetch() in try/catch. Error("URL is required") is thrown synchronously when request.url is empty or missing. ResponseError with status_code 401 when OLLAMA_API_KEY is missing or invalid. ResponseError with non-2xx status when the target URL is unreachable or returns an error (the ollama.com proxy relays target site errors). Agent tools that use webFetch to retrieve web content must handle both auth failures and content retrieval failures; a failed fetch should return a graceful error message to the agent rather than crashing the tool loop.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[3][4][5]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]raw.githubusercontent.com/ollama/ollama-jshttps://raw.githubusercontent.com/ollama/ollama-js/main/README.md
2. [2]github.com/ollama/ollama-jshttps://github.com/ollama/ollama-js
3. [3]raw.githubusercontent.com/ollama/ollama-jshttps://raw.githubusercontent.com/ollama/ollama-js/main/src/browser.ts
4. [4]raw.githubusercontent.com/ollama/ollama-jshttps://raw.githubusercontent.com/ollama/ollama-js/main/src/utils.ts
5. [5]github.com/ollama/ollama-jshttps://github.com/ollama/ollama-js/blob/main/README.md
6. [6]raw.githubusercontent.com/ollama/ollama-jshttps://raw.githubusercontent.com/ollama/ollama-js/main/src/index.ts