{"record":{"id":"44f112d66ff16e38","repo":"abhigyanpatwari/GitNexus","slug":"embedding-dimension-mismatch-endpoint-returned","errorCode":null,"errorMessage":"Embedding dimension mismatch: endpoint returned ${vec.length}d vector, but expected ${expected}d. ${hint}","messagePattern":"Embedding dimension mismatch: endpoint returned (.+?)d vector, but expected (.+?)d\\. (.+?)","errorType":"exception","errorClass":"HttpEmbeddingError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/http-client.ts","lineNumber":618,"sourceCode":"      // into the FLOAT[N] column which would cause a cryptic Kuzu error.\n      //\n      // Unlike the cardinality check this one stays *outside* the retry loop,\n      // deliberately. The expected width is `config.dimensions ?? DEFAULT_DIMS`\n      // (GITNEXUS_EMBEDDING_DIMS), which is NOT the `dimensions` value\n      // `httpEmbedBatch` receives — that is `config.requestDimensions`, which\n      // `GITNEXUS_EMBEDDING_REQUEST_DIMS` can set to a different number or to\n      // `undefined` (`omit`). More importantly a width mismatch is an operator\n      // *configuration* error, not an endpoint fault: retrying it three times\n      // can never change the answer, and routing it through the retry loop\n      // would count a healthy endpoint's responses toward the shared circuit\n      // breaker. The message is an actionable config hint, so it is terminal\n      // on the first attempt by design (#2790).\n      const expected = config.dimensions ?? DEFAULT_DIMS;\n      if (vec.length !== expected) {\n        const hint = config.dimensions\n          ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'\n          : `Set GITNEXUS_EMBEDDING_DIMS=${vec.length} to match your model output.`;\n        throw new HttpEmbeddingError(\n          `Embedding dimension mismatch: endpoint returned ${vec.length}d vector, ` +\n            `but expected ${expected}d. ${hint}`,\n        );\n      }\n\n      allVectors.push(vec);\n    }\n  }\n\n  return allVectors;\n};\n\n/**\n * Embed a single query text via the HTTP backend.\n * Convenience for MCP search where only one vector is needed.\n *\n * @param text - Query text to embed\n * @returns Embedding vector as number array","sourceCodeStart":600,"sourceCodeEnd":636,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/embeddings/http-client.ts#L600-L636","documentation":"An HttpEmbeddingError thrown by httpEmbed when an embedding vector's width does not match the expected dimension (config.dimensions ?? DEFAULT_DIMS, i.e. GITNEXUS_EMBEDDING_DIMS or 384). It is thrown outside the retry loop deliberately: a width mismatch is an operator configuration error, not an endpoint fault, so retrying cannot change the answer and routing it through the retry loop would unfairly penalize a healthy endpoint via the shared circuit breaker (#2790). The message names both widths and emits an actionable config hint.","triggerScenarios":"httpEmbed after httpEmbedBatch returns well-shaped items: new Float32Array(item.embedding).length !== (config.dimensions ?? 384). The endpoint's actual vector width disagrees with the declared/expected width. Common when GITNEXUS_EMBEDDING_DIMS is unset (default 384) but the model returns a different width, or when GITNEXUS_EMBEDDING_DIMS is set to a stale value after switching models.","commonSituations":"Switched from a 384d model to a 1536d model without updating GITNEXUS_EMBEDDING_DIMS. Left GITNEXUS_EMBEDDING_DIMS unset while using a non-384d model (default assumption is 384). Requested truncation via GITNEXUS_EMBEDDING_REQUEST_DIMS but forgot to set GITNEXUS_EMBEDDING_DIMS to the truncated width. Provider silently changed the model's output dimension.","solutions":["If GITNEXUS_EMBEDDING_DIMS is set: update it to match the returned width shown in the message (e.g. the endpoint returned 1536d → set GITNEXUS_EMBEDDING_DIMS=1536).","If GITNEXUS_EMBEDDING_DIMS is unset: the message hint tells you exactly what to set, e.g. `Set GITNEXUS_EMBEDDING_DIMS=<returned> to match your model output`.","If you requested truncation (GITNEXUS_EMBEDDING_REQUEST_DIMS=N), set GITNEXUS_EMBEDDING_DIMS=N too, since the returned width should equal the requested width.","Re-index from scratch after changing dimensions — existing FLOAT[N] vectors are not auto-migrated."],"exampleFix":"// before: using text-embedding-3-small (1536d) with default expected width\n# GITNEXUS_EMBEDDING_DIMS unset → expects 384\n\n// after\nexport GITNEXUS_EMBEDDING_DIMS=1536","handlingStrategy":"validation","validationCode":"// After a model switch, confirm the declared width matches actual output:\nconst r = await fetch(`${URL}/embeddings`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${KEY}` }, body: JSON.stringify({ model: MODEL, input: 'probe' }) });\nconst j = await r.json();\nconst actual = j.data?.[0]?.embedding?.length;\nconst declared = parseInt(process.env.GITNEXUS_EMBEDDING_DIMS ?? '384', 10);\nif (actual && actual !== declared) {\n  throw new Error(`Dimension mismatch: model returns ${actual}d but DIMS declares ${declared}`);\n}","typeGuard":"import { isHttpEmbeddingError } from 'gitnexus';\nconst isDimensionMismatch = (e: unknown): boolean =>\n  isHttpEmbeddingError(e) && e instanceof Error && e.message.startsWith('Embedding dimension mismatch');","tryCatchPattern":"try {\n  await httpEmbed(texts);\n} catch (e) {\n  if (isDimensionMismatch(e)) {\n    // message hint says exactly what to set; update GITNEXUS_EMBEDDING_DIMS and re-index\n  }\n  throw e;\n}","preventionTips":["Set GITNEXUS_EMBEDDING_DIMS to your model's native width, and to the truncated width if you use GITNEXUS_EMBEDDING_REQUEST_DIMS.","After any model change, probe the actual output width and re-index.","Keep indexer and MCP host on the same DIMS value to avoid query-time mismatch (error 139)."],"tags":["config","embeddings","dimension-mismatch"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}