apache/seatunnel · error · HugeGraphConnectorException

GRAPH_OPERATION_FAILED

GRAPH_OPERATION_FAILED

Error message

HugeGraph pagination marker did not advance for split '%s': '%s'

What it means

While paging through HugeGraph query results, the reader tracks the pagination marker (next-page token). If a response's next-page marker equals the one that was requested, pagination did not advance and the loop would spin forever, so readOnePage throws GRAPH_OPERATION_FAILED identifying the split and stuck marker.

Source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/source/HugeGraphSourceReader.java:263

                    split.isShardMode()
                            ? filterVerticesByLabel(page.getRecords(), label)
                            : page.getRecords();
            collectVertices(records, output, ctx);
            recordCount = page.getRecords().size();
            responsePage = page.getNextPage();
        } else {
            PageResult<Edge> page = fetchEdgePage(split, label, requestedPage);
            List<Edge> records =
                    split.isShardMode()
                            ? filterEdgesByLabel(page.getRecords(), label)
                            : page.getRecords();
            collectEdges(records, output, ctx);
            recordCount = page.getRecords().size();
            responsePage = page.getNextPage();
        }

        if (responsePage != null && responsePage.equals(requestedPage)) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.GRAPH_OPERATION_FAILED,
                    String.format(
                            "HugeGraph pagination marker did not advance for split '%s': '%s'",
                            split.splitId(), responsePage));
        }

        split.setLastEmittedId(this.lastEmittedId);
        split.setPage(responsePage);
        totalRecords += recordCount;
        pageCount++;
        if (recordCount == 0 && responsePage != null) {
            LOG.debug(
                    "HugeGraph source received an empty intermediate page for split '{}'; continuing",
                    split.splitId());
        }
        if (responsePage == null) {
            split.setFinished(true);
            LOG.info(

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Retry the job/split; transient server-side paging issues often resolve after the HugeGraph server recovers.
  2. Reduce page size / scan scope so each request is smaller and less likely to hit the server paging bug.
  3. Upgrade HugeGraph to a version with pagination fixes; check server logs for pagination errors.
  4. Capture the split id and marker from the message and report/check the specific shard on the server.
Defensive patterns

Strategy: retry

Validate before calling

// preflight: small paginated query works and advances
// GET /graphs/<g>/gremlin with page limit and assert next != null differs across calls

Try / catch

try {
  reader.pollNext(...);
} catch (HugeGraphConnectorException e) {
  if (e.getErrorCode() == GRAPH_OPERATION_FAILED) {
    // retry the split after backoff, or fail and let checkpoint restart the reader
  }
}

Prevention

When it happens

Trigger: During pollNext() -> readOnePage(), the server returns a page whose getNextPage() equals the requested page marker, after records were collected, indicating the server is not advancing the cursor.

Common situations: HugeGraph server bug or degraded state returning stale pagination tokens; very large label/page combinations hitting server-side paging limits; repeated identical queries after server restart or pagination cache invalidation.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/c7a2097b0b095122. Report an issue: GitHub.