abhigyanpatwari/GitNexus · error

The structural index is incomplete. Run gitnexus analyze…

Error message

The structural index is incomplete. Run gitnexus analyze --force first.

What it means

The index metadata exists but has incrementalInProgress set, meaning an incremental analyze did not finish and the structural index is incomplete. Embedding sync refuses to run against a partial graph because embeddings reference nodes that may not exist yet.

Solutions

1. Run `gitnexus analyze --force` to complete a full structural rebuild, then re-run the embeddings sync.
2. Check no other analyze process is currently running against the same index.
3. If the flag is stale after a crash, the forced rebuild will reset it.
4. Avoid killing analyze mid-run; let it complete before switching to embeddings sync.

Example fix

// before
$ gitnexus embeddings-sync .   # Error: structural index is incomplete
// after
$ gitnexus analyze --force
$ gitnexus embeddings-sync .

// Detect a stale/unfinished incremental run before syncing:
import { readFileSync, existsSync } from 'node:fs';
function indexIncomplete(repoPath) {
  const metaPath = join(repoPath, '.gitnexus');
  if (!existsSync(metaPath)) return true;
  try {
    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
    return meta.incrementalInProgress === true;
  } catch { return true; }
}
if (indexIncomplete(repo)) await run('gitnexus analyze --force');

try {
  await gitnexus.embeddingsSync(repo);
} catch (err) {
  if (err.message.includes('structural index is incomplete')) {
    await run('gitnexus analyze --force');
    await gitnexus.embeddingsSync(repo);
  } else throw err;
}

When it happens

Trigger: A previous `gitnexus analyze --incremental` (or interrupted analyze) left meta.incrementalInProgress=true; running embeddings sync before completing a structural rebuild.

Common situations: An analyze run was killed mid-way (CI timeout, Ctrl+C, crash); a concurrent analyze was aborted; the metadata flag persisted after an unclean shutdown.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Cannot sync embeddings: the index checkpoint was written by
• No GitNexus index found for
• The LadybugDB graph store at
• The LadybugDB graph store at
• analyze --watch does not support

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

Appendix: source

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

/** Add missing embeddings directly to a healthy index, checkpointing periodically. */
export const embeddingsSyncCommand = async (inputPath?: string): Promise<void> => {
  const repoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
  if (!repoPath) throw new Error('Not inside a git repository. Pass a repository path.');

  const { lbugPath, metaPath } = getStoragePaths(repoPath);
  const metaDir = path.dirname(metaPath);
  const lock = await acquireIndexLock(metaDir);
  try {
    requireExclusiveIndexLock(
      lock,
      `Cannot acquire the index lock at ${metaDir}; refusing an unlocked embeddings sync.`,
    );
    const meta = await loadMeta(metaDir);
    if (!meta)
      throw new Error(`No GitNexus index found for ${repoPath}. Run gitnexus analyze first.`);
    if (meta.incrementalInProgress) {
      throw new Error('The structural index is incomplete. Run gitnexus analyze --force first.');
    }

    let lbugStat;
    try {
      lbugStat = await lstat(lbugPath);
    } catch {
      throw new Error(
        `The LadybugDB graph store at ${lbugPath} is missing. Run gitnexus analyze first.`,
      );
    }
    if (!lbugStat.isFile()) {
      throw new Error(
        `The LadybugDB graph store at ${lbugPath} is not a usable database file. Run gitnexus analyze first.`,
      );
    }

    const { resolveEmbeddingIdentity } = await import('../core/embeddings/embedding-identity.js');
    const identity = resolveEmbeddingIdentity();

View on GitHub (pinned to ac9a4e9abd)