abhigyanpatwari/GitNexus · error · Error

Bridge query prepare failed: ${errMsg}

Error message

Bridge query prepare failed: ${errMsg}

What it means

Thrown by queryBridge when LadybugDB's conn.prepare(cypher) returns a statement whose isSuccess() is false — i.e. the bridge database rejected the Cypher as syntactically invalid, semantically unsupported, or referencing unknown identifiers. The underlying driver message is appended so the exact LadybugDB parse error is visible. Only the parameterized branch (params present and non-empty) calls prepare(); the no-param branch goes straight to conn.query.

Source

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

    } catch (err: unknown) {
      const msg = err instanceof Error ? err.message : String(err);
      if (!msg.includes(LBUG_ALREADY_EXISTS_MSG)) throw err;
    }
  }
}

export async function queryBridge<T>(
  handle: BridgeHandle,
  cypher: string,
  params?: Record<string, LbugValue>,
): Promise<T[]> {
  const run = async (): Promise<T[]> => {
    const conn = handle._conn as lbug.Connection;
    if (params && Object.keys(params).length > 0) {
      const stmt = await conn.prepare(cypher);
      if (!stmt.isSuccess()) {
        const errMsg = await stmt.getErrorMessage();
        throw new Error(`Bridge query prepare failed: ${errMsg}`);
      }
      const queryResult = await conn.execute(stmt, params);
      const result = unwrapQueryResult(queryResult);
      return (await result.getAll()) as T[];
    }
    const queryResult = await conn.query(cypher);
    const result = unwrapQueryResult(queryResult);
    return (await result.getAll()) as T[];
  };
  // Cached RO handles are shared across concurrent @group callers, so serialize
  // conn ops per handle (a LadybugDB Connection is not safe for concurrent
  // queries — conn-lock.ts). Uncached/writable handles (the writeBridge temp DB)
  // 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();
}

View on GitHub (pinned to d540b00184)

Solutions

1. Read the appended errMsg verbatim — it is LadybugDB's own parse error and pinpoints the offending token.
2. If the error references an unknown table (NODE TABLE / REL TABLE), ensure ensureBridgeSchema(handle) was run against the current bridge DB before this query.
3. If the schema is correct, validate the cypher string against the LadybugDB version bundled (check BRIDGE_SCHEMA_QUERIES and the queries module for the exact table/rel names the statement references).
4. Regenerate the bridge DB (closeBridgeDb + invalidateBridgeCache, then re-run group sync) if the on-disk bridge.lbug predates the current schema.

Example fix

// before — typo'd keyword, prepare() fails
await queryBridge(handle, 'MATCHH (n:Symbol) RETURN n', { id });

// after — valid Cypher, prepare() succeeds
await queryBridge(handle, 'MATCH (n:Symbol) WHERE n.id = $id RETURN n', { id });

// queryBridge throws on prepare() failure; catch to fall back or report
typealias
declare const _t: never; // placeholder, replace below
// (see pattern below)
try {
  const rows = await queryBridge<SymbolRow>(handle, cypher, params);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Bridge query prepare failed:')) {
    logger.error({ cypher, params, msg: err.message }, 'Bridge query rejected');
    throw err; // prepare errors are not transient — surface, do not retry as-is
  }
  throw err;
}

When it happens

Trigger: Calling queryBridge(handle, cypher, params) with a Cypher string that LadybugDB cannot compile: syntax errors, misspelled keywords (e.g. MATCHH), unknown node/rel table names from a stale or missing schema (ensureBridgeSchema not run), or a Cypher feature unsupported by the bridge's LadybugDB build.

Common situations: Stale bridge DB whose schema lags the query (group synced, contracts changed, but ensureBridgeSchema not re-run against the current BRIDGE_SCHEMA_QUERIES); a typo in a hand-written Cypher literal added during group feature work; a LadybugDB version bump that dropped/renamed a keyword the queries depend on.

Related errors

• Prepare failed: ${errMsg}
• Bridge query returned an empty QueryResult array
• Batch execution failed for rows ${firstRow + 1}-${firstRow +
• LadybugDB not initialized for repo "${repoId}". Call initLbu
• Prepare failed: ${errMsg}

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