What causes "Embedding service not initialized" in ruvnet/ruflo?

Await the embedding service's initialize() before any embed() call (gate request handling on startup completion)

Embedding service not initialized

Error message

Embedding service not initialized

What it means

The cached embedding wrapper in the hooks ReasoningBank module throws from embed(text) when its internal service handle is null — meaning initialize() was never called (or did not complete) so there is no IEmbeddingService to delegate to. The cache lookup happens first, so previously embedded strings still return; only new text triggers the throw.

Source

Thrown at v3/@claude-flow/hooks/src/reasoningbank/index.ts:954

        cacheSize: 1000,
      });
    }
  }

  async embed(text: string): Promise<Float32Array> {
    const cacheKey = text.slice(0, 200);
    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey)!;
    }

    if (this.service) {
      const result = await this.service.embed(text);
      const embedding = result.embedding;
      this.cache.set(cacheKey, embedding);
      return embedding;
    }

    throw new Error('Embedding service not initialized');
  }
}

/**
 * Fallback embedding service (hash-based)
 */
class FallbackEmbeddingService implements IEmbeddingService {
  private dimensions: number;
  private cache: Map<string, Float32Array> = new Map();

  constructor(dimensions: number = 384) {
    this.dimensions = dimensions;
  }

  async embed(text: string): Promise<Float32Array> {
    const cacheKey = text.slice(0, 200);
    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey)!;

View on GitHub (pinned to fa13ee4ad6)

Solutions

Await the embedding service's initialize() before any embed() call (gate request handling on startup completion)
If the real embedding backend failed to initialize, fall back to the hash-based FallbackEmbeddingService instead of leaving the wrapper uninitialized
Expose and check an isInitialized flag (or track readiness in your own bootstrap) before scheduling embed work

Example fix

// before
const embedder = createEmbeddingService(config);
// initialize() never awaited (or failed silently)
await embedder.embed('hello'); // throws: not initialized

// after
const embedder = createEmbeddingService(config);
await embedder.initialize(); // must complete first
await embedder.embed('hello');

Defensive patterns

Strategy: validation

Validate before calling

// Gate embed calls on completed initialization
let embeddingsReady = false;
async function boot() {
  await embedder.initialize();
  embeddingsReady = true;
}
async function safeEmbed(text: string): Promise<Float32Array> {
  if (!embeddingsReady) throw new Error('embeddings not initialized yet');
  return embedder.embed(text);
}

Type guard

interface InitializableEmbedder {
  initialize(): Promise<void>;
  embed(t: string): Promise<Float32Array>;
}
function isReady(flag: boolean): boolean {
  return flag; // pair with the readiness flag set after initialize() resolves
}

Try / catch

try {
  vec = await embedder.embed(text);
} catch (e) {
  if (e instanceof Error && e.message === 'Embedding service not initialized') {
    await embedder.initialize(); // one retry after completing init
    vec = await embedder.embed(text);
  } else {
    throw e;
  }
}

Prevention

Always await initialize() in bootstrap before accepting traffic that embeds text
If the real embedding backend fails to init, switch to the hash-based fallback service instead of continuing half-initialized
Add a readiness check to health probes that covers embedding initialization

When it happens

Trigger: Constructing the embedding service wrapper and calling await embedder.embed(text) before await embedder.initialize() resolves — e.g. fire-and-forget initialization, a failed initialize whose error was swallowed, or embed invoked from a request handler racing the startup sequence.

Common situations: Missing await on an async initialize in bootstrap; initialize() throwing for the real embedding backend and the caller continuing anyway; embed called during shutdown after the service was torn down; tests skipping initialization for speed.

Related errors

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