abhigyanpatwari/GitNexus · error · HttpEmbeddingError

Embedding dimension mismatch: endpoint returned ${embedding.

Error message

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

What it means

An HttpEmbeddingError thrown by httpEmbedQuery when the single returned embedding's width does not match the expected dimension (config.dimensions ?? DEFAULT_DIMS, i.e. GITNEXUS_EMBEDDING_DIMS or 384). It is the query-path counterpart of error 136, with the same rationale (terminal on first attempt, not retried, because it is a configuration error). It prevents a width mismatch from reaching the Kuzu FLOAT[N] cast in search queries. The message names both widths and emits an actionable hint.

Source

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

    config.minIntervalMs,
    config.timeoutMs,
  );
  // 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 d540b00184)

Solutions

1. Match the MCP host's GITNEXUS_EMBEDDING_DIMS to the width the index was built with (it must equal the indexer's setting, or both must be unset consistently).
2. If GITNEXUS_EMBEDDING_DIMS is unset, set it to the returned width shown in the message.
3. If you changed dimensions, re-index from scratch so stored FLOAT[N] vectors match the query width.
4. Ensure indexer and MCP server read the same env source (.env / systemd unit) so they cannot drift.

Example fix

// before: query expects 384 but model returns 1536
# GITNEXUS_EMBEDDING_DIMS unset in MCP host

// after
export GITNEXUS_EMBEDDING_DIMS=1536   # must match the indexed width
# restart the MCP server, and re-index if the index was built at a different width

// Ensure MCP host DIMS matches the indexed width:
const indexedWidth = /* width the index was built with, e.g. from index metadata */;
const declared = parseInt(process.env.GITNEXUS_EMBEDDING_DIMS ?? '384', 10);
if (indexedWidth !== declared) {
  throw new Error(`Query DIMS (${declared}) != indexed width (${indexedWidth}); re-index or align env`);
}

import { isHttpEmbeddingError } from 'gitnexus';
const isDimensionMismatch = (e: unknown): boolean =>
  isHttpEmbeddingError(e) && e instanceof Error && e.message.startsWith('Embedding dimension mismatch');

try {
  await httpEmbedQuery(text);
} catch (e) {
  if (isDimensionMismatch(e)) {
    // align MCP host GITNEXUS_EMBEDDING_DIMS with the indexed width; re-index if needed
  }
  throw e;
}

When it happens

Trigger: httpEmbedQuery after httpEmbedBatch returns one item: items[0].embedding.length !== (config.dimensions ?? 384). The MCP search path hits this when the configured expected width disagrees with the model's actual output width.

Common situations: MCP host has a different GITNEXUS_EMBEDDING_DIMS than the indexer used, or both have it unset while the model is not 384d. Switched models and updated the indexer env but not the MCP host env (or vice versa), so search queries a different width than was indexed. Requested truncation via GITNEXUS_EMBEDDING_REQUEST_DIMS without setting GITNEXUS_EMBEDDING_DIMS.

Related errors

• Embedding dimension mismatch: endpoint returned ${vec.length
• ${source} must be true/false or a non-negative integer (node
• ${source} must be a boolean or a non-negative integer (node
• ${name} must be a positive integer, got "${value}"
• embedding device must be one of auto, dml, cuda, cpu, wasm;

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