abhigyanpatwari/GitNexus · error · Error

Bridge query returned an empty QueryResult array

Error message

Bridge query returned an empty QueryResult array

What it means

Thrown by the private unwrapQueryResult helper when LadybugDB's conn.query/conn.execute returns an array of QueryResult objects that is empty. GitNexus always dispatches a single statement, so a top-level empty array is a driver-contract regression, not normal output. The explicit throw prevents a downstream `.getAll()` on undefined producing a confusing stack.

Source

Thrown at gitnexus/src/core/group/bridge-db.ts:590

  // are single-threaded — they're absent from bridgeEntryByHandle and skip the
  // lock at zero cost.
  const entry = bridgeEntryByHandle.get(handle);
  return entry ? withHandleLock(entry, run) : run();
}

/**
 * LadybugDB's `conn.query` / `conn.execute` can return either a single
 * `QueryResult` (for a single statement) or an array of them (when a
 * multi-statement script is dispatched). We always pass a single statement,
 * so the array form is a wrapper we unwrap here — but an empty top-level
 * array would cause `.getAll()` on `undefined` and crash with a confusing
 * stack. Throwing an explicit error makes a driver-contract regression
 * visible immediately instead of masking it.
 */
function unwrapQueryResult(queryResult: lbug.QueryResult | lbug.QueryResult[]): lbug.QueryResult {
  if (Array.isArray(queryResult)) {
    if (queryResult.length === 0) {
      throw new Error('Bridge query returned an empty QueryResult array');
    }
    return queryResult[0];
  }
  return queryResult;
}

/**
 * Release a caller's reference to a bridge handle.
 *
 * - **Cache-owned handle** (returned by `getCachedBridgeReadOnly`): this is the
 *   matching *release* for that acquire — it decrements the lease refcount, it
 *   does NOT close the native handle. The cache owns the lifetime; the handle
 *   closes on explicit `invalidateBridgeCache`, mtime-eviction, or process
 *   shutdown. If the entry was already evicted and this is the last lease, the
 *   deferred native close fires here (exactly once).
 * - **Uncached/writable handle** (e.g. the `writeBridge` temp DB): closes the
 *   native handle for real (CHECKPOINT-flush for writable handles).
 *

View on GitHub (pinned to d540b00184)

Solutions

1. Check the LadybugDB driver version in use — if it was recently bumped, compare its QueryResult contract against the version GitNexus was written for.
2. If this reproduces in tests, fix the mock/stub to return a single QueryResult object (or a one-element array), not [].
3. If it reproduces against a real bridge DB, capture the exact cypher and params and file a driver-contract regression with the LadybugDB maintainers.
4. As a last resort, rebuild the bridge DB from scratch (the on-disk bridge.lbug may be in a corrupted state).

Example fix

// test stub returning the wrong shape — triggers the guard
mockConn.query = async () => [];

// after — single QueryResult object as the contract expects
mockConn.query = async () => ({ getAll: async () => [], close: async () => {} });

// unwrapQueryResult's empty-array throw indicates a driver regression.
// Catch and report, but treat as a bug to investigate, not a normal runtime path.
try {
  const rows = await queryBridge<T>(handle, cypher);
} catch (err) {
  if (err instanceof Error && err.message === 'Bridge query returned an empty QueryResult array') {
    logger.error({ cypher }, 'LadybugDB driver-contract regression: empty QueryResult array');
  }
  throw err;
}

When it happens

Trigger: Any code path through queryBridge or writeBridge where the LadybugDB driver returns [] instead of a single QueryResult — e.g. a future driver version changing multi-statement handling, or a monkeypatched/mock connection returning the wrong shape in tests.

Common situations: LadybugDB driver upgraded to a version that returns [] for certain DDL or no-op statements; a test stub mocking conn.query with an empty array; a corrupted connection returning an unexpected response shape after a native crash.

Related errors

• Bridge query prepare failed: ${errMsg}
• [embed] Failed to delete stale embedding rows — aborting to
• GitNexus could not move the LadybugDB WAL sidecar at ${dbPat
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui

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