ruvnet/ruflo · error · Error

embedding failed

Error message

embedding failed

What it means

Thrown inside the semantic mode of the pathfinder (agentdb k-hop query) when generateEmbedding(nodeId) returns a falsy value (null, undefined, empty array). The semantic path needs a query vector to score candidate edges by cosine similarity, so a missing embedding aborts the branch. It usually indicates the embeddings backend (ONNX/agentic-flow) is unavailable, the model failed to load, or the input string could not be embedded.

Source

Thrown at v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts:1073

            return {
              success: true, mode, nodeId, depth,
              results: rows.map((r: unknown[]) => ({ nodeId: r[0], depth: r[1] })),
              count: rows.length,
              backend: 'sql-cte',
              elapsedMs: Date.now() - t0,
            };
          }
        } catch { /* db unavailable */ }

        return { success: false, error: 'No graph backend available for k-hop query', mode, nodeId };
      }

      // ── semantic mode ────────────────────────────────────────────────────────
      if (mode === 'semantic') {
        try {
          const { generateEmbedding } = await getMemInit();
          const queryEmb = await generateEmbedding(nodeId);
          if (!queryEmb) throw new Error('embedding failed');

          const { getBridgeDb } = await getGraphEdgeWriter();
          // #2246 fix: lazy-create memory.db on first pathfinder call so
          // fresh environments work without a pre-existing memory init.
          const db = await getBridgeDb(undefined, { createIfMissing: true });
          if (!db) return { success: false, error: 'graph_edges DB unavailable (sql.js could not load)', hint: 'Check Node version + try `ruflo memory init` to initialize manually.', mode, nodeId };

          // Load all rows with embedding_ref and score by cosine.
          // better-sqlite3 API — `db.exec(sql, params)` (sql.js) silently
          // throws "datatype mismatch" because exec ignores params, so `?`
          // binds to nothing and SQLite rejects the LIMIT clause.
          const rows = db.prepare(
            `SELECT id, source_id, target_id, relation, weight, embedding_ref FROM graph_edges WHERE embedding_ref IS NOT NULL LIMIT ?`,
          ).raw().all(budget.maxNodesVisited) as unknown[][];
          const { decodeEmbedding } = await getEmbQuant();

          const scored: Array<{ nodeId: string; score: number; relation: string }> = [];
          const qv = new Float32Array(queryEmb.embedding);

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Run `ruflo memory init` (or `npx @claude-flow/cli memory init`) to initialize the embeddings backend.
2. Verify the ONNX model file exists and the runtime loads: check the embeddings log for model-load errors.
3. Confirm nodeId is a non-empty string with real content; if you intended structural lookup, use mode='structural' instead of 'semantic'.
4. On an unsupported host, fall back to structural mode (the tool returns a structured error rather than throwing for unavailable backends).

Example fix

// before — semantic query before init
await pathfinder({ mode: 'semantic', nodeId: 'auth', depth: 2 });
// after
await callMCPTool('memory_init', {});
await pathfinder({ mode: 'semantic', nodeId: 'auth', depth: 2 });

let embeddingsReady = false;
async function ensureEmbeddings() {
  if (embeddingsReady) return;
  const { generateEmbedding } = await getMemInit();
  const probe = await generateEmbedding('test');
  if (!probe) throw new Error('embeddings backend unavailable — run `ruflo memory init`');
  embeddingsReady = true;
}
await ensureEmbeddings();

null

try { return await pathfinder({ mode: 'semantic', nodeId, depth }); }
catch (e) {
  if (/^embedding failed$/.test(String(e?.message ?? ''))) {
    return await pathfinder({ mode: 'structural', nodeId, depth }); // graceful fallback
  }
  throw e;
}

When it happens

Trigger: Running a semantic pathfinder query before embeddings are initialized; the ONNX model file is missing or the wrong architecture; generateEmbedding hit an internal error and returned null instead of throwing; an empty or whitespace-only nodeId that produced no vector.

Common situations: Fresh environment where `ruflo memory init` was not run; CI host without the ONNX runtime native binary; the embeddings model path is misconfigured; an integrator passed an empty nodeId.

Related errors

• Invalid embedding model name: ${embeddingModel}
• Invalid embedding value at index ${i}: expected finite numbe
• statusline-generator: could not locate .claude/helpers/statu
• dimension is required when creating a new memory file
• HNSW pattern limit reached (${HNSW_MAX_SAFE_PATTERNS}).

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/9493251dcdad641e. Report an issue: GitHub.