LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui

Error message

LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebuild the index with `gitnexus analyze --force <repo-path> --index-only` and restart `gitnexus serve`.
  Original error: ${msg.slice(0, 200)}
  The workspace appears to be read-only — mount it read-write to perform shadow replay recovery, or re-run `gitnexus analyze` on a writable filesystem to rebuild the index.

What it means

lbug-adapter.ts line 637 (ensureReadOnlyConnectionUsable): after a read-path shadow-replay failure, the adapter tries to open a writable connection to perform shadow replay recovery; if that open fails with EROFS, EACCES, or EPERM, the standard sidecar-recovery message gains a suffix explaining the workspace is read-only. The operator must either mount the storage read-write so recovery can run, or rebuild the index on a writable filesystem.

Source

Thrown at gitnexus/src/core/lbug/lbug-adapter.ts:637

      await closeLbugConnection(handle);
      return await reopenReadOnlyAfterMissingShadow(dbPath, err);
    }
    if (!isReadOnlyShadowReplayError(err)) {
      await closeLbugConnection(handle);
      throw err;
    }
    shadowReplayErr = err;
  }

  await closeLbugConnection(handle);

  let writable: LbugConnectionHandle;
  try {
    writable = await openLbugConnection(lbug, dbPath);
  } catch (openErr) {
    const code = extractErrnoCode(openErr);
    if (code === 'EROFS' || code === 'EACCES' || code === 'EPERM') {
      throw new Error(
        shadowSidecarRecoveryMessage(dbPath, shadowReplayErr) +
          '\n  The workspace appears to be read-only — mount it read-write to perform shadow replay recovery,' +
          ' or re-run `gitnexus analyze` on a writable filesystem to rebuild the index.',
      );
    }
    throw openErr;
  }
  let missingShadowError: unknown;
  try {
    await queryAndDrain(writable.conn, READ_ONLY_SHADOW_REPLAY_PROBE);
  } catch (err) {
    if (isMissingShadowSidecarError(err)) {
      missingShadowError = err;
    } else {
      throw err;
    }
  } finally {
    await closeLbugConnection(writable);

View on GitHub (pinned to aac7515d2a)

Solutions

Mount the storage directory read-write (or fix permissions) and re-run so shadow replay recovery can complete
Alternatively, on a writable machine run `gitnexus analyze --force <repo-path> --index-only` and redistribute the rebuilt index to the read-only location
Design CI to build indexes on writable storage first, then mount them read-only for serving — a read-only index with a healthy sidecar never needs this recovery

Example fix

# before
$ docker run -v indexes:/indexes:ro ... gitnexus serve
# after: give the recovery path write access, or rebuild elsewhere
$ gitnexus analyze --force /repo --index-only   # on writable storage
$ docker run -v indexes:/indexes:ro ... gitnexus serve

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs';

// Before serving from shared/read-only storage, verify the index is writable-recoverable
try {
  fs.accessSync(path.dirname(dbPath), fs.constants.W_OK);
} catch {
  console.warn('Storage is read-only: a missing-sidecar index here cannot self-recover. Serve only verified indexes, or mount read-write.');
}

Try / catch

try {
  await openReadOnly(dbPath);
} catch (err) {
  if (err instanceof Error && err.message.includes('workspace appears to be read-only')) {
    // remount storage read-write and retry once, or rebuild the index on writable storage and redistribute
  }
  throw err;
}

Prevention

Build indexes on writable storage, verify serve starts, and only then mount them read-only for serving
In containers, mount the storage volume rw for any role that may trigger recovery (serve, analyze)
Ensure the serving process's user owns or can write the storage directory

When it happens

Trigger: The index lives on a read-only volume (ro Docker mount, mounted CI artifact, write-protected share) AND the checkpoint sidecar is missing so recovery needs a writable open; permission bits deny the process write access to the storage dir.

Common situations: Serving prebuilt indexes from read-only container layers; shared RO network mounts in orgs that distribute indexes; running serve under a user without write rights on the storage directory.

Related errors

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