abhigyanpatwari/GitNexus · error

LadybugDB checkpoint sidecar is present but unreachable for

Error message

LadybugDB checkpoint sidecar is present but unreachable for ${dbPath}. The .shadow file is on disk, so the open likely failed on path reachability or a file lock (antivirus, another process holding a handle, or a non-ASCII path) rather than a missing sidecar. Check filesystem access and locks; only run `gitnexus analyze --force <repo-path> --index-only` if the index is genuinely broken.
  Original error: ${msg.slice(0, 200)}

What it means

guardWalQuarantine refuses to quarantine the WAL during recovery when the .shadow checkpoint sidecar is present on disk but unreachable (state.kind === 'present-shadow-refuse'). Presence of the .shadow means the open failed on path reachability or a file lock (antivirus, another process holding a handle, non-ASCII path) rather than a missing sidecar, so quarantining would be wrong; the error includes the first 200 chars of the original error.

Solutions

  1. Check filesystem access and locks: close other GitNexus MCP/serve processes and any antivirus/backup handles on the .gitnexus directory.
  2. Verify the repo path is fully reachable (no network drive issues, avoid non-ASCII path segments if possible).
  3. Only if the index is genuinely broken, run `gitnexus analyze --force <repo-path> --index-only` to rebuild.
Defensive patterns

Strategy: try-catch

Validate before calling

import fs from 'node:fs';
const shadowExists = fs.existsSync(dbPath + '.shadow');
if (shadowExists) {
  console.warn('.shadow sidecar present; ensure no AV/backup locks and the path is reachable before recovery.');
}

Try / catch

try {
  await runRecovery(dbPath);
} catch (err) {
  if (err instanceof Error && err.message.includes('quarantine WAL')) {
    console.error('Close AV/backup handles and other GitNexus processes, then retry; avoid non-ASCII paths.');
  } else throw err;
}

Prevention

When it happens

Trigger: Running a recovery mode through guardWalQuarantine against a dbPath whose WAL open failed while a .shadow sidecar exists; the sidecar is on disk but the database open failed due to OS-level locks, antivirus scanning, or an unreachable/non-ASCII path.

Common situations: Antivirus or backup software holding a handle on sidecar files; the repo moved to a path with non-ASCII characters; two processes contending for the database; network drive where the sidecar path is temporarily unreachable.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at gitnexus/src/core/lbug/sidecar-recovery.ts:378

 * the warning text (e.g. 'read-only', 'writable', 'pool read-only recovery').
 */
export const guardWalQuarantine = async (
  dbPath: string,
  mode: string,
  triggeringErr: unknown,
  logger: SidecarRecoveryLogger,
  crashEvidence?: WalCrashEvidence,
): Promise<void> => {
  const state = await inspectLbugSidecars(dbPath);
  if (state.kind === 'wal-with-shadow') {
    warnOnce(
      logger,
      `${dbPath}:present-shadow-refuse:${mode}`,
      `GitNexus: refusing to quarantine WAL at ${dbPath}.wal during ${mode} recovery — ` +
        'the .shadow sidecar is present on disk, so the open likely failed on path reachability or a lock ' +
        'rather than a missing shadow. Run `gitnexus analyze --force <repo-path> --index-only` if the index is genuinely broken.',
    );
    throw new Error(presentShadowUnreachableMessage(dbPath, triggeringErr));
  }
  if (state.kind === 'orphan-wal') {
    if (crashEvidence?.kind === 'fts-inplace-checkpointed') {
      const { failed } = await quarantineSidecarsForDirtyRecovery(dbPath, (message) =>
        logger.warn(message),
      );
      if (failed.length > 0) {
        throw new Error(ftsCrashParkFailureMessage(failed[0]!));
      }
      return;
    }
    warnOnce(
      logger,
      `${dbPath}:large-wal-refuse:${mode}`,
      `GitNexus: refusing to quarantine large WAL (${state.walBytes} bytes) at ${dbPath}.wal during ${mode} recovery; ` +
        'manual recovery required — run `gitnexus analyze --force <repo-path> --index-only`.',
    );
    throw new Error(shadowSidecarRecoveryMessage(dbPath, triggeringErr));

View on GitHub (pinned to ac9a4e9abd)