{"record":{"id":"9493251dcdad641e","repo":"ruvnet/ruflo","slug":"embedding-failed","errorCode":null,"errorMessage":"embedding failed","messagePattern":"embedding failed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts","lineNumber":1073,"sourceCode":"            return {\n              success: true, mode, nodeId, depth,\n              results: rows.map((r: unknown[]) => ({ nodeId: r[0], depth: r[1] })),\n              count: rows.length,\n              backend: 'sql-cte',\n              elapsedMs: Date.now() - t0,\n            };\n          }\n        } catch { /* db unavailable */ }\n\n        return { success: false, error: 'No graph backend available for k-hop query', mode, nodeId };\n      }\n\n      // ── semantic mode ────────────────────────────────────────────────────────\n      if (mode === 'semantic') {\n        try {\n          const { generateEmbedding } = await getMemInit();\n          const queryEmb = await generateEmbedding(nodeId);\n          if (!queryEmb) throw new Error('embedding failed');\n\n          const { getBridgeDb } = await getGraphEdgeWriter();\n          // #2246 fix: lazy-create memory.db on first pathfinder call so\n          // fresh environments work without a pre-existing memory init.\n          const db = await getBridgeDb(undefined, { createIfMissing: true });\n          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 };\n\n          // Load all rows with embedding_ref and score by cosine.\n          // better-sqlite3 API — `db.exec(sql, params)` (sql.js) silently\n          // throws \"datatype mismatch\" because exec ignores params, so `?`\n          // binds to nothing and SQLite rejects the LIMIT clause.\n          const rows = db.prepare(\n            `SELECT id, source_id, target_id, relation, weight, embedding_ref FROM graph_edges WHERE embedding_ref IS NOT NULL LIMIT ?`,\n          ).raw().all(budget.maxNodesVisited) as unknown[][];\n          const { decodeEmbedding } = await getEmbQuant();\n\n          const scored: Array<{ nodeId: string; score: number; relation: string }> = [];\n          const qv = new Float32Array(queryEmb.embedding);","sourceCodeStart":1055,"sourceCodeEnd":1091,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts#L1055-L1091","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `ruflo memory init` (or `npx @claude-flow/cli memory init`) to initialize the embeddings backend.","Verify the ONNX model file exists and the runtime loads: check the embeddings log for model-load errors.","Confirm nodeId is a non-empty string with real content; if you intended structural lookup, use mode='structural' instead of 'semantic'.","On an unsupported host, fall back to structural mode (the tool returns a structured error rather than throwing for unavailable backends)."],"exampleFix":"// before — semantic query before init\nawait pathfinder({ mode: 'semantic', nodeId: 'auth', depth: 2 });\n// after\nawait callMCPTool('memory_init', {});\nawait pathfinder({ mode: 'semantic', nodeId: 'auth', depth: 2 });","handlingStrategy":"validation","validationCode":"let embeddingsReady = false;\nasync function ensureEmbeddings() {\n  if (embeddingsReady) return;\n  const { generateEmbedding } = await getMemInit();\n  const probe = await generateEmbedding('test');\n  if (!probe) throw new Error('embeddings backend unavailable — run `ruflo memory init`');\n  embeddingsReady = true;\n}\nawait ensureEmbeddings();","typeGuard":"null","tryCatchPattern":"try { return await pathfinder({ mode: 'semantic', nodeId, depth }); }\ncatch (e) {\n  if (/^embedding failed$/.test(String(e?.message ?? ''))) {\n    return await pathfinder({ mode: 'structural', nodeId, depth }); // graceful fallback\n  }\n  throw e;\n}","preventionTips":["Run `ruflo memory init` before issuing semantic queries.","Smoke-test generateEmbedding at startup so model-load failures surface early.","Fall back to structural mode when embeddings are unavailable rather than crashing the query."],"tags":["embeddings","agentdb","pathfinder","semantic","init"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}