{"record":{"id":"daf53547d30b350f","repo":"ruvnet/ruflo","slug":"provider-unavailable-daf535","errorCode":"PROVIDER_UNAVAILABLE","errorMessage":"Provider custom is unavailable","messagePattern":"Provider custom is unavailable","errorType":"exception","errorClass":"ProviderUnavailableError","httpStatus":503,"severity":"error","filePath":"v3/@claude-flow/providers/src/ruvector-provider.ts","lineNumber":634,"sourceCode":"        router: data.router_metrics,\n      },\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('custom', {\n        message,\n        hint: 'Start RuVector server: npx @ruvector/ruvllm serve',\n      });\n    }\n\n    throw new LLMProviderError(\n      message,\n      `RUVECTOR_${response.status}`,\n      'custom',\n      response.status,\n      true,\n      errorData\n    );\n  }\n\n  /**\n   * Get SONA learning metrics\n   */","sourceCodeStart":616,"sourceCodeEnd":652,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/providers/src/ruvector-provider.ts#L616-L652","documentation":"RuVectorProvider.handleErrorResponse classifies a failure as connection-level when response.status === 0 or the error text contains 'connection', and throws ProviderUnavailableError (code PROVIDER_UNAVAILABLE, statusCode 503, retryable=true) with the hint 'Start RuVector server: npx @ruvector/ruvllm serve'. This error means 'server not reachable', not 'bad request' — it is the signal ProviderManager's fallback logic keys on.","triggerScenarios":"Any RuVector HTTP call while the server process is down; baseUrl pointing at the wrong port/host so the connection is refused; a gateway between client and server reporting a connection failure in its error body.","commonSituations":"Forgot to start the RuVector server before running the swarm; Docker container port not published or using localhost from another container; stale host in config after the server moved; CI environments with no local model server at all.","solutions":["Start the server: npx @ruvector/ruvllm serve","Confirm the provider's baseUrl/port matches the serving process (curl the baseUrl root or /v1/sona/metrics)","In Docker: publish the port and address the container by service name, not localhost","Configure a second provider in ProviderManager so fallback engages when ruvector is unavailable"],"exampleFix":"# before: server never started, only ruvector configured\n# → Provider custom is unavailable\n\n# after: start the server and keep a fallback provider\nnpx @ruvector/ruvllm serve &\nproviders: [\n  { provider: 'ruvector', baseUrl: 'http://localhost:8080' },\n  { provider: 'openai' },\n]","handlingStrategy":"fallback","validationCode":"import { ProviderUnavailableError } from './types.js';\n// optional pre-flight probe before a batch of calls\nasync function ruvectorUp(baseUrl: string): Promise<boolean> {\n  try {\n    const res = await fetch(`${baseUrl}/v1/sona/metrics`);\n    return res.status < 500; // any answer means the server is reachable\n  } catch {\n    return false;\n  }\n}","typeGuard":"import { isLLMProviderError } from './types.js';\nfunction isRuvectorUnavailable(e: unknown): boolean {\n  return isLLMProviderError(e) && e.code === 'PROVIDER_UNAVAILABLE' && e.provider === 'custom';\n}","tryCatchPattern":"try {\n  return await ruvector.complete(request);\n} catch (e) {\n  if (isRuvectorUnavailable(e)) {\n    return await fallbackProvider.complete(request); // or let ProviderManager's completWithFallback do this\n  }\n  throw e;\n}","preventionTips":["Enable ProviderManager fallback (config.fallback.enabled) with a second provider so unavailability fails over automatically","Probe the server once at startup instead of discovering downtime mid-request","In containers, wire healthchecks for the RuVector service, not just the app"],"tags":["ruvector","llm","connection-refused","failover","local-server"],"backgroundTag":"connection-refused","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}