abhigyanpatwari/GitNexus · error · HttpEmbeddingError

Embedding dimension mismatch: endpoint returned

Error message

Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, but expected ${expected}d. ${hint}

What it means

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.

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.

Example fix

# before
# index built with 384d model; env now:
export GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small   # 1536d
# -> Embedding dimension mismatch: endpoint returned 1536d vector, but expected 384d.

# after
export GITNEXUS_EMBEDDING_MODEL=<original-384d-model>   # match the indexed width
# ...or re-index with the new model and GITNEXUS_EMBEDDING_DIMS=1536

Defensive patterns

Strategy: validation

Validate before calling

// Before search, confirm query-time dims equal index-time dims.
import { getHttpDimensions } from './core/embeddings/http-client.js';

const indexedDims = await getIndexEmbeddingWidth(); // read from your index metadata
const configured = getHttpDimensions() ?? 384;
if (indexedDims !== configured) {
  throw new Error(
    `dims drift: index=${indexedDims} config=${configured} — restore the indexed model/dims or re-analyze`,
  );
}

Type guard

import { HttpEmbeddingError } from './core/embeddings/http-client.js';

export const isDimensionMismatchError = (e: unknown): e is HttpEmbeddingError =>
  e instanceof HttpEmbeddingError && e.message.startsWith('Embedding dimension mismatch');

Try / catch

try {
  vec = await httpEmbedQuery(text);
} catch (err) {
  if (isDimensionMismatchError(err)) {
    // Terminal: do not retry. Signal the operator to realign model/dims.
    return { error: 'embedding-dims-drift', detail: err.message };
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-08-20). Data as JSON: /api/errors/3d79601083d3f9f7. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/embeddings/http-client.ts:731

    config.timeoutMs,
    config.retryTimeouts,
  );
  // Defensive backstop like the `httpEmbed` one above: an empty `data` array is
  // now a cardinality mismatch (0 vectors for 1 text) rejected and retried
  // inside `httpEmbedBatch`, so this branch is unreachable in practice.
  if (!items.length) {
    throw new HttpEmbeddingError(`Embedding endpoint returned empty response (${safeUrl(url)})`);
  }

  const embedding = items[0].embedding;
  // Same dimension checks as httpEmbed — catch mismatches before they
  // reach the Kuzu FLOAT[N] cast in search queries.
  const expected = config.dimensions ?? DEFAULT_DIMS;
  if (embedding.length !== expected) {
    const hint = config.dimensions
      ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'
      : `Set GITNEXUS_EMBEDDING_DIMS=${embedding.length} to match your model output.`;
    throw new HttpEmbeddingError(
      `Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, ` +
        `but expected ${expected}d. ${hint}`,
    );
  }
  return embedding;
};

View on GitHub (pinned to ac9a4e9abd)