abhigyanpatwari/GitNexus · error · Error

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`.\n  Original error: ${msg}\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.

What it means

Thrown by `ensureReadOnlyConnectionUsable` when the read-only shadow-replay probe fails and the writable reopen needed to replay shadow pages is blocked by a read-only workspace (openLbugConnection throws EROFS/EACCES/EPERM). It appends a read-only-specific tail to `shadowSidecarRecoveryMessage`: the missing shadow cannot be recovered in-place because the filesystem refuses writes. Two distinct remedies are valid depending on whether you can remount or must rebuild elsewhere.

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 d540b00184)

Solutions

1. Remount the workspace read-write (or grant the serve user write permission) so shadow-replay recovery can run.
2. Re-run `gitnexus analyze` on a writable filesystem to rebuild a complete index, then serve the rebuilt index.
3. If read-only serving is intentional and permanent, always rebuild on a writable FS and copy the complete sidecar set over.

function isReadOnlyWorkspaceShadowError(err): boolean {
  return /workspace appears to be read-only/i.test(
    err instanceof Error ? err.message : String(err),
  );
}

try {
  await ensureReadOnlyConnection(dbPath);
} catch (err) {
  if (/workspace appears to be read-only/i.test(err.message)) {
    // Either remount read-write to replay the shadow, or rebuild on a writable FS.
    console.error(err.message);
    process.exit(8);
  }
  throw err;
}

When it happens

Trigger: The checkpoint `.shadow` sidecar is missing AND the workspace/storage directory is mounted read-only (EROFS) or denies writes (EACCES/EPERM), so the writable recovery open that would replay shadow pages fails at the OS level.

Common situations: Running `gitnexus serve` against a read-only mounted index directory (a common deployment for shared, immutable indexes); a container with a read-only volume mount for the storage dir; permission ACLs denying the serve user write access.

Related errors

• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• LadybugDB checkpoint sidecar is present but unreachable for
• GitNexus could not move the LadybugDB WAL sidecar at ${dbPat
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• Write operations are not allowed. The pool adapter is read-o

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