abhigyanpatwari/GitNexus · error · AnalysisNotFinalizedError

Analysis not finalized: missing

Error message

Analysis not finalized: missing ${'meta'} metadata for ${resolved} at ${storagePath} (registry: ${getGlobalRegistryPath()})

What it means

AnalysisNotFinalizedError with kind 'meta' means the index metadata file (INDEX_METADATA_FILE) could not be found at the selected storagePath, so the repository has no completed analysis receipt there. The manager throws rather than guessing, telling you where it looked and which registry it consulted.

Solutions

1. Run `gitnexus analyze` (optionally with the same storagePath) to produce the metadata file.
2. Verify storagePath / GITNEXUS_STORAGE_PATH points at the directory where analysis actually ran.
3. Re-analyze if a previous run was interrupted before finalization.
4. Check the registry path in the message to confirm you are consulting the expected registry.

Example fix

// before
await readIndex(repo); // no meta at /wrong/slot
// after
await analyze({ repo, storagePath: "/wrong/slot" });
await readIndex(repo);

import { access } from "fs/promises";
try {
  await access(path.join(storagePath, "index-meta.json"));
} catch {
  await analyze({ repoPath, storagePath }); // finalize analysis before consuming
}

try {
  await readIndex(repoPath, { storagePath });
} catch (err) {
  if (err instanceof AnalysisNotFinalizedError && err.kind === "meta") {
    await analyze({ repoPath, storagePath });
    await readIndex(repoPath, { storagePath });
  } else throw err;
}

When it happens

Trigger: Calling a finalize/read path (e.g. ensureAnalysisFinalized) after fs.access on path.join(storagePath, INDEX_METADATA_FILE) fails — the metadata file does not exist at that storage directory.

Common situations: Running query/serve/register against a repo whose analyze never completed; the storage directory was moved or GITNEXUS_STORAGE_PATH points at the wrong slot; the repo was analyzed with a different storage configuration than the current one; the .gitnexus directory was deleted or cleaned.

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

• Metadata file exists but is unreadable/corrupt; leaving…
• Analysis did not finalize for
• Could not remove the shadowed branch sub-index; keeping its…
• DiskBackedScopeTree.byId is unsupported…
• err.message

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

Appendix: source

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

 * The optional `resolvedStoragePath` carries the exact slot used by the
 * analysis. Omitting it preserves the legacy local-resolution behavior for
 * direct callers.
 */
export const assertAnalysisFinalized = async (
  repoPath: string,
  resolvedStoragePath?: string,
): Promise<void> => {
  const resolved = path.resolve(repoPath);
  const storagePath =
    resolvedStoragePath === undefined
      ? getStoragePaths(resolved).storagePath
      : validateConfiguredStoragePath(resolvedStoragePath);
  const metaPath = path.join(storagePath, INDEX_METADATA_FILE);

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

  const canonicalRepoPath = canonicalizePath(resolved);
  const canonicalStoragePath = canonicalizePath(storagePath);
  const registeredAtStoragePath = (await readRegistryStrict()).some(
    (entry) =>
      registryPathEquals(canonicalizePath(entry.path), canonicalRepoPath) &&
      registryPathEquals(canonicalizePath(entry.storagePath), canonicalStoragePath),
  );
  if (!registeredAtStoragePath) {
    throw new AnalysisNotFinalizedError(
      resolved,
      storagePath,
      'registry-entry',
      getGlobalRegistryPath(),
    );
  }
};

View on GitHub (pinned to ac9a4e9abd)