abhigyanpatwari/GitNexus · error · Error

Refusing to register

Error message

Refusing to register ${resolved}: metadata belongs to ${meta.repoPath}, not this repository.

What it means

registerRepo refuses to write a registry entry when the caller passed an explicit storagePath option but the analysis metadata receipt (meta.repoPath) describes a different repository than the one being registered. This guard prevents a changed environment or redirected registry from registering storage metadata under the wrong repo. The omitted-option path intentionally keeps legacy direct-call behavior.

Solutions

Re-run `gitnexus analyze` (or the register flow) in the target repository so fresh metadata is generated for it.
Point opts.storagePath at the storage directory that actually belongs to this repository.
Remove stale metadata from the borrowed storage directory before registering.
Omit the storagePath option if you intend legacy direct-call behavior and the metadata already matches.

Example fix

// before
await registerRepo("/repos/fork", { storagePath: "/repos/original/.gitnexus" });
// after
await registerRepo("/repos/fork", { storagePath: "/repos/fork/.gitnexus" });

Defensive patterns

Strategy: validation

Validate before calling

import { readFile } from "fs/promises";
const meta = JSON.parse(await readFile(path.join(storagePath, "index-meta.json"), "utf8"));
if (path.resolve(meta.repoPath) !== path.resolve(repoPath)) {
  throw new Error(`metadata belongs to ${meta.repoPath}, not ${repoPath}`);
}

Try / catch

try {
  await registerRepo(repoPath, { storagePath });
} catch (err) {
  if (/metadata belongs to/.test(String(err))) {
    // re-run analyze in repoPath with this storagePath, then retry
  } else throw err;
}

Prevention

Always analyze a repo with the same storagePath you later register it under.
Do not share storage directories between copies/clones of a repo.
Re-analyze after moving or renaming a project directory.
Keep GITNEXUS_STORAGE_PATH stable across commands.

When it happens

Trigger: Calling registerRepo with opts.storagePath set while the metadata file at that storage slot was produced for another repository path (meta.repoPath differs from the repo being registered, per canonicalized path comparison).

Common situations: A project directory was moved/renamed and an old .gitnexus metadata is being pointed at the new path; a copy of a repo (clone/fork) reuses the original's storage directory; GITNEXUS_STORAGE_PATH/ROOT env vars were changed between analyze and register.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

  // which is where the cross-platform divergence actually matters.
  const resolved = path.resolve(repoPath);
  const storagePath =
    opts?.storagePath === undefined
      ? getStoragePaths(resolved).storagePath
      : validateConfiguredStoragePath(opts.storagePath);

  // Canonical form used strictly for comparison — `realpathSync.native`
  // expands macOS /var → /private/var and Windows 8.3 → long-name,
  // falling back to `path.resolve` when the path doesn't exist.
  const canonicalInput = canonicalizePath(repoPath);

  // Production write paths pass the storage slot they already validated. Do
  // not let a changed environment/registry redirect their registry entry, and
  // require the metadata receipt to describe that same repository and slot.
  // The omitted-option path deliberately retains legacy direct-call behavior.
  if (opts?.storagePath !== undefined) {
    if (!registryPathEquals(canonicalizePath(meta.repoPath), canonicalInput)) {
      throw new Error(
        `Refusing to register ${resolved}: metadata belongs to ${meta.repoPath}, not this repository.`,
      );
    }
    if (
      meta.storagePath === undefined &&
      !registryPathEquals(
        canonicalizePath(storagePath),
        canonicalizePath(defaultStoragePath(resolved)),
      )
    ) {
      throw new Error(
        `Refusing to register ${resolved}: external storage metadata must bind storagePath to the selected directory.`,
      );
    }
    if (
      meta.storagePath !== undefined &&
      !registryPathEquals(canonicalizePath(meta.storagePath), canonicalizePath(storagePath))
    ) {

View on GitHub (pinned to ac9a4e9abd)