abhigyanpatwari/GitNexus · error · AnalysisNotFinalizedError

Analysis did not finalize for ${repoPath}: registry entry fo

Error message

Analysis did not finalize for ${repoPath}: registry entry for ${repoPath} was not added to ${registryPath}. The on-disk index is incomplete and was not registered. Re-run "gitnexus analyze" — if the problem persists, inspect ${storagePath} for a stale lbug.wal that signals an aborted write.

What it means

Finality variant 'registry-entry': gitnexus.json exists in the storage path, but the repo has no entry in the global registry (~/.gitnexus/registry.json) — the analyze run died between sealing metadata and registering, or the registry write itself failed (permissions, concurrent mutation, invalid JSON). The index is usable only after registration completes, so the run is reported as not finalized.

Source

Thrown at gitnexus/src/storage/repo-manager.ts:1208

 *
 * Throws {@link AnalysisNotFinalizedError} on the first failure with the
 * specific missing artifact. Pure read — does not mutate disk state.
 *
 * Callers must skip this assertion on the `alreadyUpToDate` early-return
 * path, where the rebuild was deliberately not run.
 */
export const assertAnalysisFinalized = async (repoPath: string): Promise<void> => {
  const resolved = path.resolve(repoPath);
  const { storagePath, metaPath } = getStoragePaths(resolved);

  try {
    await fs.access(metaPath);
  } catch {
    throw new AnalysisNotFinalizedError(resolved, storagePath, 'meta', getGlobalRegistryPath());
  }

  if (!(await isRepoRegistered(resolved))) {
    throw new AnalysisNotFinalizedError(
      resolved,
      storagePath,
      'registry-entry',
      getGlobalRegistryPath(),
    );
  }
};

/**
 * Thrown by {@link assertSafeStoragePath} when a registry entry's
 * `storagePath` does NOT point at the expected `<entry.path>/.gitnexus`
 * subfolder. CLI destructive commands (`remove`, `clean --all`) should
 * catch this and exit non-zero without deleting anything — the usual
 * cause is a corrupted or hand-edited `~/.gitnexus/registry.json`, and
 * proceeding would mean `fs.rm(recursive: true)` on whatever odd path
 * the entry is pointing at.
 */
export class UnsafeStoragePathError extends Error {

View on GitHub (pinned to aac7515d2a)

Solutions

Re-run gitnexus analyze — registration merges idempotently into the existing registry
Verify ~/.gitnexus/registry.json is writable and valid JSON for the current user
In CI, set HOME to a writable path
If the registry file is corrupt, back it up, remove it, and re-run analyze on the repos you need

Defensive patterns

Strategy: retry

Validate before calling

import fs from 'node:fs';
import path from 'node:path';
const registryDir = path.join(os.homedir(), '.gitnexus');
try {
  fs.accessSync(registryDir, fs.constants.W_OK);
} catch {
  throw new Error(`${registryDir} is not writable — analyze cannot register the repo`);
}

Try / catch

try {
  await runAnalyze(repo);
} catch (e) {
  if (e?.name === 'AnalysisNotFinalizedError' && e.kind === 'registry-entry') {
    return runAnalyze(repo); // registration merges idempotently — a retry finishes it
  }
  throw e;
}

Prevention

Run analyze under a user with a writable HOME (set HOME explicitly in containers)
Keep ~/.gitnexus/registry.json out of sync tools and hand edits
If a run is killed near the end, simply re-run — the seal step is idempotent

When it happens

Trigger: analyze killed in its final registration step; ~/.gitnexus/registry.json not writable (read-only home in a container, permission flip); a concurrent process rewrote the registry without this entry.

Common situations: Containers/CI running as a user without a writable HOME; a crash right at the end of a long index; registry.json corrupted by a hand edit or home-sync tool.

Related errors

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