{"record":{"id":"3d79601083d3f9f7","repo":"abhigyanpatwari/GitNexus","slug":"embedding-dimension-mismatch-endpoint-returned-3d7960","errorCode":null,"errorMessage":"Embedding dimension mismatch: endpoint returned ${embedding.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":731,"sourceCode":"    config.timeoutMs,\n    config.retryTimeouts,\n  );\n  // Defensive backstop like the `httpEmbed` one above: an empty `data` array is\n  // now a cardinality mismatch (0 vectors for 1 text) rejected and retried\n  // inside `httpEmbedBatch`, so this branch is unreachable in practice.\n  if (!items.length) {\n    throw new HttpEmbeddingError(`Embedding endpoint returned empty response (${safeUrl(url)})`);\n  }\n\n  const embedding = items[0].embedding;\n  // Same dimension checks as httpEmbed — catch mismatches before they\n  // reach the Kuzu FLOAT[N] cast in search queries.\n  const expected = config.dimensions ?? DEFAULT_DIMS;\n  if (embedding.length !== expected) {\n    const hint = config.dimensions\n      ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'\n      : `Set GITNEXUS_EMBEDDING_DIMS=${embedding.length} to match your model output.`;\n    throw new HttpEmbeddingError(\n      `Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, ` +\n        `but expected ${expected}d. ${hint}`,\n    );\n  }\n  return embedding;\n};\n","sourceCodeStart":713,"sourceCodeEnd":738,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/embeddings/http-client.ts#L713-L738","documentation":"HttpEmbeddingError thrown by httpEmbedQuery() when the single returned embedding's width differs from the expected width (GITNEXUS_EMBEDDING_DIMS or the 384 default). It is the query-path twin of the check in httpEmbed(), existing to catch mismatches before the vector reaches the Kuzu FLOAT[N] cast in search queries, where a width mismatch would fail obscurely. Terminal by design; the message carries the actual width and a config hint.","triggerScenarios":"Running a semantic search query via httpEmbedQuery() while the configured model's output width disagrees with GITNEXUS_EMBEDDING_DIMS — typically because the env var (or model) changed between indexing and querying, or the endpoint substitutes a model with different dimensions.","commonSituations":"Index embedded with a 384-dim local model, then GITNEXUS_EMBEDDING_MODEL switched to a 1536-dim hosted model before searching; GITNEXUS_EMBEDDING_DIMS=1536 left over in .env while the endpoint now serves a 768-dim model.","solutions":["Set GITNEXUS_EMBEDDING_DIMS to the width printed in the message so query vectors match.","Make sure the same model and dims are used for both indexing and querying — restore the model used at index time or re-analyze.","If the endpoint supports on-the-fly dimension reduction (e.g. OpenAI dimensions param), prefer fixing the model/dims pair rather than mixing widths across sessions."],"exampleFix":"# before\n# index built with 384d model; env now:\nexport GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small   # 1536d\n# -> Embedding dimension mismatch: endpoint returned 1536d vector, but expected 384d.\n\n# after\nexport GITNEXUS_EMBEDDING_MODEL=<original-384d-model>   # match the indexed width\n# ...or re-index with the new model and GITNEXUS_EMBEDDING_DIMS=1536","handlingStrategy":"validation","validationCode":"// Before search, confirm query-time dims equal index-time dims.\nimport { getHttpDimensions } from './core/embeddings/http-client.js';\n\nconst indexedDims = await getIndexEmbeddingWidth(); // read from your index metadata\nconst configured = getHttpDimensions() ?? 384;\nif (indexedDims !== configured) {\n  throw new Error(\n    `dims drift: index=${indexedDims} config=${configured} — restore the indexed model/dims or re-analyze`,\n  );\n}","typeGuard":"import { HttpEmbeddingError } from './core/embeddings/http-client.js';\n\nexport const isDimensionMismatchError = (e: unknown): e is HttpEmbeddingError =>\n  e instanceof HttpEmbeddingError && e.message.startsWith('Embedding dimension mismatch');","tryCatchPattern":"try {\n  vec = await httpEmbedQuery(text);\n} catch (err) {\n  if (isDimensionMismatchError(err)) {\n    // Terminal: do not retry. Signal the operator to realign model/dims.\n    return { error: 'embedding-dims-drift', detail: err.message };\n  }\n  throw err;\n}","preventionTips":["Record the model and dims used at index time (in index metadata or a stamp file) and compare them on every search start.","Never change GITNEXUS_EMBEDDING_MODEL without also checking GITNEXUS_EMBEDDING_DIMS and re-embedding.","Fail fast on the first mismatch during server warm-up instead of the first user query."],"tags":["embeddings","configuration","dimension-mismatch","search"],"backgroundTag":"embedding-dimension-mismatch","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}