abhigyanpatwari/GitNexus · error · 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

Thrown by enforceSidecarRecoveryPolicy when the sidecar inspection finds the .shadow file IS present on disk (state.kind === 'wal-with-shadow') but the DB open still failed. This is distinct from a genuinely missing sidecar: the shadow checkpoint data exists, so the failure was caused by path reachability (non-ASCII path, permission), a file lock (antivirus, another process), or an I/O error — not by missing checkpoint data. The error deliberately does NOT advise rebuilding the index (that would be destructive and unnecessary); instead it tells the user to check filesystem access and locks. The original triggering error is truncated to 200 chars and appended.

Source

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

 * the existing recovery path is safe to proceed. `mode` is a label used only in
 * the warning text (e.g. 'read-only', 'writable', 'pool read-only recovery').
 */
export const guardWalQuarantine = async (
  dbPath: string,
  mode: string,
  triggeringErr: unknown,
  logger: SidecarRecoveryLogger,
): 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') {
    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));
  }
};

export async function quarantineWalForMissingShadow(
  dbPath: string,
  options: {
    logger: SidecarRecoveryLogger;
    level?: 'debug' | 'info' | 'warn';
    reason?: string;

View on GitHub (pinned to d540b00184)

Solutions

  1. Stop all GitNexus processes and retry — the file lock from another process is the most common cause
  2. Add an antivirus exclusion for the GitNexus storage directory
  3. Check file permissions on the .shadow file and its parent directory — the GitNexus process needs read access
  4. If the repo path contains non-ASCII characters, move the repo or configure a storage root with an ASCII-only path
  5. Only run `gitnexus analyze --force <repo-path> --index-only` if you've confirmed the index is genuinely broken (not just locked)
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify .shadow file is accessible before attempting recovery
import { access, constants } from 'fs/promises';
async function isShadowAccessible(dbPath: string): Promise<boolean> {
  try {
    await access(`${dbPath}.shadow`, constants.R_OK);
    return true;
  } catch {
    return false;
  }
}

Try / catch

try {
  await enforceSidecarRecoveryPolicy(dbPath, mode, triggeringErr, logger);
} catch (e) {
  if (e instanceof Error && e.message.includes('present but unreachable')) {
    // Don't rebuild — fix the lock/path issue instead
    logger.error('Shadow sidecar present but locked — stop concurrent processes, check permissions');
  }
  throw e;
}

Prevention

When it happens

Trigger: During DB open recovery, inspectLbugSidecars detects the .shadow file exists alongside the .wal, but the open failed. This happens when the filesystem can see the file (stat succeeds) but can't read/mmap it — e.g. restrictive file permissions, a file lock held by antivirus or another GitNexus process, a non-ASCII path that confuses the native library, or an NFS/network filesystem I/O timeout.

Common situations: Windows Defender locking the .shadow file during open; another GitNexus serve/MCP process holding the file; restrictive permissions on the .gitnexus/ directory; a non-ASCII character in the repo path (common with non-English usernames on Windows); NFS mount with stale file handles.

Related errors

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