Cannot sync embeddings: this index stores FLOAT

Error message

Cannot sync embeddings: this index stores FLOAT[${meta.embeddingDims}] vectors, but this run embeds at ${EMBEDDING_DIMS} dimensions. Run `gitnexus analyze --embeddings --force` to rebuild the column at the new width.

What it means

The index's vector column was created at meta.embeddingDims but this run embeds at EMBEDDING_DIMS. Only a full rebuild can retype the column (a width change would delete rows it cannot re-insert), so the sync writer refuses rather than corrupt the table. An absent recorded width is not treated as a mismatch.

Solutions

Run `gitnexus analyze --embeddings --force` to rebuild the vector column at the new width.
Or revert the dimension/model configuration so EMBEDDING_DIMS matches meta.embeddingDims, then sync.
Pin the embedding model and dimensions in shared config/env so all runs agree.
Use a separate storage path for experiments with different dimensions.

Example fix

// before
EMBEDDING_DIMS=3072  # column built at 1536
$ gitnexus embeddings-sync .   # width mismatch
// after
$ EMBEDDING_DIMS=3072 gitnexus analyze --embeddings --force

Defensive patterns

Strategy: validation

Validate before calling

// Compare configured dims against the recorded column width before syncing:
const meta = loadIndexMeta(repo);
const dims = Number(process.env.EMBEDDING_DIMS);
if (meta && typeof meta.embeddingDims === 'number' && meta.embeddingDims !== dims) {
  await run('gitnexus analyze --embeddings --force'); // rebuild retypes the column
}

Try / catch

try {
  await gitnexus.embeddingsSync(repo);
} catch (err) {
  if (err.message.includes('FLOAT[') && err.message.includes('dimensions')) {
    await run('gitnexus analyze --embeddings --force');
    await gitnexus.embeddingsSync(repo);
  } else throw err;
}

Prevention

Freeze the embedding dimension setting for the life of an index; change it only with a forced rebuild.
Keep model and dimensions configured together and version-controlled.
Document dimension changes as schema migrations requiring `analyze --embeddings --force`.
Validate the model's output dimension against your config before first index creation.

When it happens

Trigger: Changing the embedding dimension setting after the LadybugDB column was created at the old width, then running embeddings sync — e.g. switching models with different output dimensions without forcing a rebuild.

Common situations: Model upgrades (e.g. 1536 → 3072 dims), switching to a smaller local model, or a teammate with different dimension env vars syncing into a shared index.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-15). Data as JSON: /api/errors/8f60ea45477d1401. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/cli/embeddings-sync.ts:118

            `resolves ${identity.model} (${identity.provider}) at ${identity.dimensions}. ` +
            'Run `gitnexus analyze --embeddings --force` to rebuild under the new identity.',
        );
      }
      cliInfo(decision.log);
      if (decision.action === 'resume') {
        forceReembedNodeIds = decision.pendingNodeIds;
        resumedFrom = decision.resumedFrom;
      }
    }

    // The vector column is FLOAT[N] fixed when the index was built, and the
    // pipeline deletes each batch's stale rows immediately before inserting the
    // replacements — so a width change here deletes rows it cannot re-insert.
    // `analyze` forces a full rebuild on the same mismatch; only a rebuild can
    // retype the column, so this writer refuses instead. An absent recorded
    // width is not a mismatch (see `embeddingDimsMismatch`).
    if (embeddingDimsMismatch(meta.embeddingDims, EMBEDDING_DIMS)) {
      throw new Error(
        `Cannot sync embeddings: this index stores FLOAT[${meta.embeddingDims}] vectors, ` +
          `but this run embeds at ${EMBEDDING_DIMS} dimensions. ` +
          'Run `gitnexus analyze --embeddings --force` to rebuild the column at the new width.',
      );
    }

    if (!isHttpMode()) {
      const assessment = assessLocalEmbeddingRuntime();
      if (assessment.status === 'blocked' || assessment.status === 'prefix-unloadable') {
        throw new Error(assessment.message);
      }
      if (assessment.status === 'needs-install') {
        cliInfo(`Local embedding runtime is not installed.`);
        cliInfo(`Downloading it now from your npm registry into ${getEmbeddingRuntimeDir()} …`);
        try {
          await installEmbeddingRuntime(
            {},
            getEmbeddingInstallTimeoutMs(ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS),

View on GitHub (pinned to ac9a4e9abd)