{"record":{"id":"316911e5443bd587","repo":"ruvnet/ruflo","slug":"ruvector-response-status","errorCode":"RUVECTOR_${response.status}","errorMessage":"${message}","messagePattern":"\\$\\{message\\}","errorType":"exception","errorClass":"LLMProviderError","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/providers/src/ruvector-provider.ts","lineNumber":640,"sourceCode":"    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   */\n  async getSonaMetrics(): Promise<{\n    enabled: boolean;\n    adaptationsApplied: number;\n    qualityScore: number;\n    patternsLearned: number;\n  }> {","sourceCodeStart":622,"sourceCodeEnd":658,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/providers/src/ruvector-provider.ts#L622-L658","documentation":"Non-ok response from the RuVector HTTP API that is NOT connection-level: handleErrorResponse parses the server's JSON error body and rethrows LLMProviderError with code `RUVECTOR_<status>`, provider 'custom', and retryable=true. The message is whatever the server's `error` field said (raw body if the response wasn't JSON), and the parsed body rides along in details.","triggerScenarios":"400 for an invalid request payload or unknown model name; 404 when baseUrl's path doesn't match the route called; 422/500 for server-side inference or router failures; any status whose body doesn't mention 'connection'.","commonSituations":"baseUrl path prefix mismatch with the deployed server version; model not loaded into RuVector; version skew between the provider's request shape (sona_options, router_options) and the server API; transient 500s under load.","solutions":["Read the message — it is the server's own error field and names the failing input","Reproduce manually: curl the same endpoint with the same body to see the raw response","Check baseUrl path and that every model name referenced exists on the server","Retry with backoff on 5xx (retryable is true); do not blind-retry 4xx","If 4xx persists, align request options with the server version (drop sona/router extras via enableSona/enableFastGrnn toggles)"],"exampleFix":"// before\nconst cfg = { provider: 'ruvector', baseUrl: 'http://localhost:8080/v2', model: 'mistral' };\n// → RUVECTOR_404: 'unknown route'\n\n// after\nconst cfg = { provider: 'ruvector', baseUrl: 'http://localhost:8080', model: 'mistral' };","handlingStrategy":"retry","validationCode":"async function ruvectorHealthy(baseUrl: string): Promise<boolean> {\n  try {\n    const res = await fetch(`${baseUrl}/v1/sona/metrics`);\n    return res.ok;\n  } catch {\n    return false;\n  }\n}\nif (!(await ruvectorHealthy(cfg.baseUrl))) throw new Error('RuVector server not healthy');","typeGuard":"import { isLLMProviderError } from './types.js';\nfunction isRuvectorStatusError(e: unknown): boolean {\n  return isLLMProviderError(e) && e.code.startsWith('RUVECTOR_');\n}","tryCatchPattern":"try {\n  return await ruvector.complete(request);\n} catch (e) {\n  if (isRuvectorStatusError(e) && e.retryable && (e.statusCode ?? 0) >= 500) {\n    return await retryWithBackoff(() => ruvector.complete(request), 3);\n  }\n  throw e; // 4xx: fix the request, don't retry\n}","preventionTips":["Validate baseUrl and model names against the running server before dispatch","Branch on statusCode: retry only 5xx, treat 4xx as a request bug","Log the embedded server error message — it usually names the offending field"],"tags":["ruvector","llm","http-status","retryable"],"backgroundTag":"llm-provider-http-error","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}