ruvnet/ruflo · error · LLMProviderError

RUVECTOR_${response.status}

RUVECTOR_${response.status}

Error message

${message}

What it means

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.

Source

Thrown at v3/@claude-flow/providers/src/ruvector-provider.ts:640

    const errorText = await response.text();
    let errorData: { error?: string };

    try {
      errorData = JSON.parse(errorText);
    } catch {
      errorData = { error: errorText };
    }

    const message = errorData.error || 'Unknown error';

    if (response.status === 0 || message.includes('connection')) {
      throw new ProviderUnavailableError('custom', {
        message,
        hint: 'Start RuVector server: npx @ruvector/ruvllm serve',
      });
    }

    throw new LLMProviderError(
      message,
      `RUVECTOR_${response.status}`,
      'custom',
      response.status,
      true,
      errorData
    );
  }

  /**
   * Get SONA learning metrics
   */
  async getSonaMetrics(): Promise<{
    enabled: boolean;
    adaptationsApplied: number;
    qualityScore: number;
    patternsLearned: number;
  }> {

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Read the message — it is the server's own error field and names the failing input
2. Reproduce manually: curl the same endpoint with the same body to see the raw response
3. Check baseUrl path and that every model name referenced exists on the server
4. Retry with backoff on 5xx (retryable is true); do not blind-retry 4xx
5. If 4xx persists, align request options with the server version (drop sona/router extras via enableSona/enableFastGrnn toggles)

Example fix

// before
const cfg = { provider: 'ruvector', baseUrl: 'http://localhost:8080/v2', model: 'mistral' };
// → RUVECTOR_404: 'unknown route'

// after
const cfg = { provider: 'ruvector', baseUrl: 'http://localhost:8080', model: 'mistral' };

async function ruvectorHealthy(baseUrl: string): Promise<boolean> {
  try {
    const res = await fetch(`${baseUrl}/v1/sona/metrics`);
    return res.ok;
  } catch {
    return false;
  }
}
if (!(await ruvectorHealthy(cfg.baseUrl))) throw new Error('RuVector server not healthy');

import { isLLMProviderError } from './types.js';
function isRuvectorStatusError(e: unknown): boolean {
  return isLLMProviderError(e) && e.code.startsWith('RUVECTOR_');
}

try {
  return await ruvector.complete(request);
} catch (e) {
  if (isRuvectorStatusError(e) && e.retryable && (e.statusCode ?? 0) >= 500) {
    return await retryWithBackoff(() => ruvector.complete(request), 3);
  }
  throw e; // 4xx: fix the request, don't retry
}

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

• OLLAMA_${response.status}
• PROVIDER_UNAVAILABLE
• MCP server "${server.name}" returned HTTP ${httpStatus}: ${h
• release download failed: HTTP ${response.status} for ${url}
• Unknown template preset: ${template}. Use: ${Object.keys(pre

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/316911e5443bd587. Report an issue: GitHub.