apache/seatunnel · error · IllegalArgumentException

Page number must be greater than 0

Error message

Page number must be greater than 0

What it means

PageBaseServlet.writeJsonWithPagination paginates a JSON array using the 'page' (or rows) query parameters. It computes start=(page-1)*rows and rejects page < 1 with 'Page number must be greater than 0'. Pagination is 1-based; page 0 or negative is invalid.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/rest/servlet/PageBaseServlet.java:56

    protected void writeJsonWithPagination(
            HttpServletRequest req, HttpServletResponse resp, JsonArray jsonArray)
            throws IOException {
        int total = jsonArray.size();

        // fetch pagination params, if page exist, then paginate data，pagination data format like:
        // {"data": [], "total": 10}
        Map<String, String> parameterMap = getParameterMap(req);
        if (parameterMap != null && parameterMap.containsKey(pageParam)) {
            int page = Integer.parseInt(parameterMap.get(pageParam));
            int rows =
                    parameterMap.get(rowsParam) != null
                            ? Integer.parseInt(parameterMap.get(rowsParam))
                            : 10;
            int start = (page - 1) * rows;
            if (start > total || page < 1) {
                throw new IllegalArgumentException(
                        page < 1
                                ? "Page number must be greater than 0"
                                : "Page number exceeds total pages");
            }
            JsonArray paginatedArray = new JsonArray();
            jsonArray
                    .values()
                    .subList(start, Math.min(start + rows, total))
                    .forEach(
                            t -> {
                                paginatedArray.add(t);
                            });
            JsonObject paginatedObj = new JsonObject();
            paginatedObj.add("data", paginatedArray);
            paginatedObj.add("total", total);
            writeJson(resp, paginatedObj);
        } else {
            writeJson(resp, jsonArray);
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Send page >= 1, e.g. ?page=1&rows=10
2. Fix client pagination math to start from 1
3. Clamp/validate the page parameter in the client before the request
4. Return 400 (not 500) with a message clarifying 1-based pagination

Example fix

// before
fetch(`/finished-jobs?page=0&rows=10`);
// after
const page = Math.max(1, Number(rawPage) || 1);
fetch(`/finished-jobs?page=${page}&rows=10`);

int page = Math.max(1, requestedPage);

boolean isPositivePage(int p) { return p >= 1; }

try { fetchPage(page, rows); } catch (IllegalArgumentException e) { fetchPage(1, rows); }

When it happens

Trigger: GET a paginated REST endpoint (e.g. checkpoint history / finished-jobs) with page=0, page=-1, or a non-positive numeric page parameter.

Common situations: Clients using 0-based page indexes against a 1-based API; UI pagination controls starting at 0; scripting loops that run one extra iteration with page=0; copy-paste of page=0 from logs.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Page number exceeds total pages
• Parameter 'pluginName' cannot be empty.
• The jobId must not be empty.
• The jobId must not be empty.
• The jobId must not be empty.

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