{"record":{"id":"8db7052eeea3c701","repo":"ruvnet/ruflo","slug":"provider-unavailable","errorCode":"PROVIDER_UNAVAILABLE","errorMessage":"Provider ollama is unavailable","messagePattern":"Provider ollama is unavailable","errorType":"exception","errorClass":"ProviderUnavailableError","httpStatus":503,"severity":"error","filePath":"v3/@claude-flow/providers/src/ollama-provider.ts","lineNumber":393,"sourceCode":"      finishReason: data.done ? 'stop' : 'length',\n      latency: data.total_duration ? data.total_duration / 1e6 : undefined, // Convert ns to ms\n    };\n  }\n\n  private async handleErrorResponse(response: Response): Promise<never> {\n    const errorText = await response.text();\n    let errorData: { error?: string };\n\n    try {\n      errorData = JSON.parse(errorText);\n    } catch {\n      errorData = { error: errorText };\n    }\n\n    const message = errorData.error || 'Unknown error';\n\n    if (response.status === 0 || message.includes('connection')) {\n      throw new ProviderUnavailableError('ollama', {\n        message,\n        hint: 'Ensure Ollama is running: ollama serve',\n      });\n    }\n\n    throw new LLMProviderError(\n      message,\n      `OLLAMA_${response.status}`,\n      'ollama',\n      response.status,\n      true,\n      errorData\n    );\n  }\n}\n","sourceCodeStart":375,"sourceCodeEnd":409,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/providers/src/ollama-provider.ts#L375-L409","documentation":"OllamaProvider treats status 0 (fetch-level network failure) or an error body containing 'connection' as ProviderUnavailableError with the hint 'Ensure Ollama is running: ollama serve'. Ollama is a local daemon (default http://localhost:11434), so this fires when the server is not reachable rather than when a request is malformed. Marked retryable (503).","triggerScenarios":"complete()/streamComplete() while the ollama daemon is not running; config.apiUrl pointing at the wrong host/port; a Docker container reaching 'localhost' instead of the host's Ollama; OLLAMA_HOST changed on the server.","commonSituations":"Forgot `ollama serve` after a reboot; running the app in Docker where localhost is the container itself; Ollama bound to 127.0.0.1 only while the app runs on another host; port changed from 11434.","solutions":["Start the daemon: `ollama serve`, then verify with curl http://localhost:11434/api/tags","Point config.apiUrl at the real host:port - from Docker use http://host.docker.internal:11434 (not localhost)","Run Ollama as a systemd/launchd service so it survives reboots","For remote daemons, ensure OLLAMA_HOST is set server-side and the port is reachable (no firewall drop)"],"exampleFix":"// before\nconst provider = new OllamaProvider({\n  name: 'ollama',\n  config: { model: 'llama3.1:8b', apiUrl: 'http://localhost:11434' }, // app runs in Docker\n});\n\n// after\nconst provider = new OllamaProvider({\n  name: 'ollama',\n  config: { model: 'llama3.1:8b', apiUrl: 'http://host.docker.internal:11434' },\n});","handlingStrategy":"validation","validationCode":"async function ollamaUp(apiUrl = 'http://localhost:11434'): Promise<boolean> {\n  try {\n    const ctrl = new AbortController();\n    const t = setTimeout(() => ctrl.abort(), 2000);\n    const r = await fetch(`${apiUrl}/api/tags`, { signal: ctrl.signal });\n    clearTimeout(t);\n    return r.ok;\n  } catch {\n    return false; // daemon not reachable -> expect PROVIDER_UNAVAILABLE\n  }\n}","typeGuard":"import { ProviderUnavailableError } from './types.js';\nfunction isOllamaUnavailable(e: unknown): e is ProviderUnavailableError {\n  return e instanceof ProviderUnavailableError && e.provider === 'ollama';\n}","tryCatchPattern":"try {\n  return await ollamaProvider.complete(req);\n} catch (e) {\n  if (isOllamaUnavailable(e)) {\n    return manager.complete(req, cloudProvider); // fail over to a cloud provider\n  }\n  throw e;\n}","preventionTips":["Run a preflight health check (GET /api/tags) before dispatching to the local daemon","Run `ollama serve` under systemd/launchd so it survives reboots","From Docker, configure apiUrl as host.docker.internal:11434, never localhost"],"tags":["ollama","connection","local-server","docker","service-unavailable"],"backgroundTag":"connection-refused","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}