Batch execution failed for rows ${firstRow + 1}-${firstRow +

Error message

Batch execution failed for rows ${firstRow + 1}-${firstRow + subBatch.length}: ${msg} (${queryPreview})

What it means

Thrown during LadybugDB batch writeback when executing a prepared statement across a sub-batch of parameter rows (SUB_BATCH_SIZE=4) fails mid-flight. The error wraps the underlying LadybugDB execute failure with the row range, the original error message, and a 120-char preview of the Cypher query. This is a write-path error: the writeback pipeline uses batched parameterized INSERTs to populate graph nodes/edges, and any per-row execution failure (constraint violation, type mismatch, native crash) aborts the entire sub-batch.

Source

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

    const firstRow = subBatchIndex * SUB_BATCH_SIZE;
    // One critical section per sub-batch: the prepare + its executes run with
    // exclusive access to the connection (so the WAL checkpoint driver cannot
    // interleave a CHECKPOINT mid-batch), while the lock is released between
    // sub-batches to let the driver checkpoint during a long writeback.
    await withConnLock(async () => {
      const stmt = await c.prepare(cypher);
      if (!stmt.isSuccess()) {
        const errMsg = await stmt.getErrorMessage();
        throw new Error(`Prepare failed: ${errMsg}`);
      }
      try {
        for (const params of subBatch) {
          await drainQueryResult(await c.execute(stmt, params));
        }
      } catch (e) {
        const msg = e instanceof Error ? e.message : String(e);
        const queryPreview = cypher.replace(/\s+/g, ' ').slice(0, 120);
        throw new Error(
          `Batch execution failed for rows ${firstRow + 1}-${firstRow + subBatch.length}: ${msg} (${queryPreview})`,
        );
      }
      // Note: LadybugDB PreparedStatement doesn't require explicit close()
    });
  }
};

/**
 * Node and edge totals for the open index.
 *
 * `edges` is `undefined` when the count could NOT BE TAKEN, and that is a
 * different fact from zero. It used to be initialised to 0 with the query in a
 * swallowing `catch`, so a WAL/lock contention throw during finalize — a
 * documented hazard on this exact call — returned a measured-looking 0. The
 * collapse check downstream then read a perfectly healthy index as a total
 * write collapse, which is precisely the confident-zero failure that check
 * exists to prevent.

View on GitHub (pinned to d540b00184)

Solutions

Read the wrapped `msg` and `queryPreview` in the error — the underlying LadybugDB message pinpoints whether it's a type error, constraint violation, or IO failure
If the error is IO-related (disk full, WAL write failure), free disk space and re-run `gitnexus analyze` — the writeback is transactional and a failed sub-batch leaves the incremental dirty flag set, triggering a full rebuild on next run
If the error is a type/schema mismatch, check the node/edge property types in `schema.ts` against the parameter objects being passed — ensure all Cypher placeholders ($name) have matching keys in every params object
If a specific row's data is the cause, inspect the source extraction for the failing row range (firstRow+1 to firstRow+subBatch.length) to find the malformed symbol/file
Re-run `gitnexus analyze` after fixing the root cause — the crash-recovery dirty flag forces a clean full rebuild

Example fix

// before — params object missing a required key or wrong type
const params = { name: symbol.name };
// after — supply all placeholders with correct types
const params = { name: symbol.name, kind: symbol.kind, filePath: symbol.filePath, line: Number(symbol.line) };

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate all parameter objects before batch insert
function validateBatchParams(paramsList: Record<string, unknown>[], requiredKeys: string[]): void {
  for (let i = 0; i < paramsList.length; i++) {
    for (const key of requiredKeys) {
      if (!(key in paramsList[i])) {
        throw new Error(`Row ${i}: missing required parameter key "${key}"`);
      }
    }
  }
}

Type guard

function isValidBatchParams(params: unknown, requiredKeys: readonly string[]): params is Record<string, unknown> {
  if (typeof params !== 'object' || params === null) return false;
  const obj = params as Record<string, unknown>;
  return requiredKeys.every((k) => k in obj);
}

Try / catch

try {
  await batchExecuteWithConnLock(cypher, paramsList);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Batch execution failed')) {
    // Parse row range from message, log the specific failing batch
    logger.error(`Writeback batch failed — dirty flag set, next run will full-rebuild`, e);
  }
  throw e; // Re-throw: the caller's crash-recovery must set the dirty flag
}

Prevention

Always validate parameter object keys against the Cypher placeholder set before calling batch insert
Use TypeScript types to enforce parameter object shapes at compile time
Run `gitnexus analyze` in a CI pipeline after schema changes to catch type mismatches early
Monitor disk space before starting large writebacks to prevent IO failures mid-batch

When it happens

Trigger: Calling the internal batch-insert function (which wraps c.prepare + c.execute in a withConnLock critical section) with a paramsList where one or more parameter objects contain values incompatible with the prepared Cypher schema — e.g. a null where the column requires a non-null, a string where INT32 is expected, or a parameter key that doesn't exist in the Cypher placeholder set. Also triggered by native LadybugDB runtime exceptions during execute(): buffer manager exhaustion, WAL write failure under disk pressure, or a closed/invalidated connection.

Common situations: A schema change in GitNexus core that adds a new node property but the writeback code hasn't been updated to supply it; a very large paramsList where one row has malformed data extracted from an exotic source file; disk-full conditions during incremental re-writeback where the WAL can't grow; concurrent process holding a write lock that causes execute to fail; running on LadybugDB 0.18.0 where a type coercion edge case rejects certain parameter shapes.

Related errors

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