No GitNexus index found for

Error message

No GitNexus index found for ${repoPath}. Run gitnexus analyze first.

What it means

After acquiring the index lock, the sync loads the index metadata file. If loadMeta returns null there is no GitNexus index metadata for the resolved repo path, meaning `gitnexus analyze` has never been run (or the metadata file was deleted). Sync needs an existing healthy index to add embeddings to.

Solutions

Run `gitnexus analyze` in the repository first, then re-run the embeddings sync.
Confirm the metadata exists: check for `.gitnexus/` (or your GITNEXUS_STORAGE_PATH) in the repo root.
Make sure you are pointing at the correct repository path if you passed one explicitly.
If metadata was deleted accidentally, restore from backup or rebuild via analyze.

Example fix

// before
$ gitnexus embeddings-sync .   # Error: No GitNexus index found
// after
$ gitnexus analyze
$ gitnexus embeddings-sync .

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
import { join } from 'node:path';
function hasGitNexusIndex(repoPath) {
  return existsSync(join(repoPath, '.gitnexus'));
}
if (!hasGitNexusIndex(repo)) await run('gitnexus analyze');

Try / catch

try {
  await gitnexus.embeddingsSync(repo);
} catch (err) {
  if (err.message.includes('No GitNexus index found')) {
    await run('gitnexus analyze');
    await gitnexus.embeddingsSync(repo); // retry once after indexing
  } else throw err;
}

Prevention

Always run `gitnexus analyze` before embeddings sync on a fresh clone or clean checkout.
Remember .gitnexus/ is local (typically gitignored) — it does not survive fresh clones.
In CI, add an index-creation step before any embeddings work.
Double-check GITNEXUS_STORAGE_PATH points at the directory containing the index you intend to sync.

When it happens

Trigger: Running embeddings sync against a repo with no `.gitnexus/` metadata file — first run on a fresh clone, after `gitnexus clean`, after manually deleting the index directory, or pointing the command at the wrong repo path.

Common situations: Fresh clone where the index was never generated; CI container where only the source was checked out; running the command in a sibling directory with a similar name.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

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

} from '../core/embeddings/runtime-support.js';
import { reapEmbeddingSidecarSafely } from '../core/embeddings/embedding-sidecar-reap.js';

/** 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.`,
      );
    }

View on GitHub (pinned to ac9a4e9abd)