#Embeddings Provider Failures

#Overview

This guide covers embedding provider failures in OpenClaw's memory system, based on src/memory/embeddings.ts. Embeddings power vector similarity search for memory retrieval. When providers fail, the system gracefully degrades to full-text search (FTS) only mode.

#Symptoms

#Missing API Key Errors

• Log message: "No API key found for provider"
• Error includes specific provider name (OpenAI, Voyage, etc.)
• Memory search continues with FTS only

#FTS-Only Mode

• Memory search returns only text matches
• No vector similarity results
• Log message: "providerUnavailableReason" with details

#Provider Chain Exhaustion

• Primary provider fails
• Fallback provider also fails
• System reports all providers unavailable

#Degraded Search Quality

• Search results less relevant than expected
• Missing semantically similar items
• Only exact keyword matches returned

#Root Causes

#1. Missing API Keys (Lines 91-94)

Provider configured but API key not available:

function isMissingApiKeyError(error: unknown): boolean {
  const msg = String(error).toLowerCase();
  return msg.includes('api key') || msg.includes('apikey');
}

Detection: Error message parsing for key-related strings Common causes:

• Environment variable not set
• Config file missing credentials section
• API key expired or revoked

Recovery: Graceful degradation to FTS-only mode

#2. Fallback Chain Failure (Lines 204-211)

All providers in fallback chain fail:

Chain structure:

1. Primary provider (e.g., local Ollama)
2. Secondary provider (e.g., OpenAI)
3. FTS-only mode (no embeddings)

Common causes:

• Both primary and secondary missing API keys
• Network connectivity issues
• All providers rate-limited simultaneously

Recovery: Return null provider, enable FTS-only mode

#3. Fallback Provider Missing Key (Lines 228-246)

Primary fails, fallback also has missing key:

Detection logic:

if (isMissingApiKeyError(primaryError)) {
  // Try fallback
  if (isMissingApiKeyError(fallbackError)) {
    // Both missing keys - return null
    return { provider: null, reason: "Both providers missing API keys" };
  }
}

Recovery: System-wide FTS-only mode with detailed reason logging

#4. Network and Rate Limit Errors

Provider reachable but requests fail:

Common HTTP status codes:

• 429: Rate limit exceeded
• 500-503: Provider service errors
• Timeout: Network latency or provider overload

Recovery: Automatic retry with exponential backoff (via src/memory/batch-http.ts)

#5. Auto-Selection Failures

When provider: "auto" is configured:

Selection logic:

1. Try local provider first (node-llama-cpp)
2. Fall back to remote providers
3. Each provider checked for availability

Common causes:

• node-llama-cpp not installed or failed to build
• Local model files missing
• GPU/memory requirements not met

#Recovery Mechanisms

#Graceful Degradation Flow