alibaba/nacos · error · IllegalArgumentException

fetchPageLimit error

Error message

fetchPageLimit error

What it means

Thrown by AuthEmbeddedPaginationHelperImpl.fetchPage when the SQL count query (sqlCountRows) returns null instead of an integer row count. This indicates the count SQL itself returned no result row — the database could not produce a count. The message 'fetchPageLimit error' is generic and does not reveal the underlying SQL issue.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/persistence/embedded/AuthEmbeddedPaginationHelperImpl.java:74

    @Override
    public Page<E> fetchPage(final String sqlCountRows, final String sqlFetchRows,
        final Object[] args,
        final int pageNo, final int pageSize, final RowMapper rowMapper) {
        return fetchPage(sqlCountRows, sqlFetchRows, args, pageNo, pageSize, null, rowMapper);
    }
    
    @Override
    public Page<E> fetchPage(final String sqlCountRows, final String sqlFetchRows, Object[] args,
        final int pageNo,
        final int pageSize, final Long lastMaxId, final RowMapper rowMapper) {
        if (pageNo <= 0 || pageSize <= 0) {
            throw new IllegalArgumentException("pageNo and pageSize must be greater than zero");
        }
        
        // Query the total number of current records
        Integer rowCountInt = databaseOperate.queryOne(sqlCountRows, args, Integer.class);
        if (rowCountInt == null) {
            throw new IllegalArgumentException("fetchPageLimit error");
        }
        
        // Count pages
        int pageCount = rowCountInt / pageSize;
        if (rowCountInt > pageSize * pageCount) {
            pageCount++;
        }
        
        // Create Page object
        final Page<E> page = new Page<>();
        page.setPageNumber(pageNo);
        page.setPagesAvailable(pageCount);
        page.setTotalCount(rowCountInt);
        
        if (pageNo > pageCount) {
            return page;
        }
        

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Check the server logs for the actual Derby SQL error preceding this exception.
2. Verify auth-related Derby tables exist (e.g., permissions, roles, users) in the embedded database.
3. If the database is corrupted, stop the server, remove the embedded Derby data directory, and restart to reinitialize.
4. Ensure no custom auth SQL templates are overriding the default count queries incorrectly.

Example fix

// Not a code fix — diagnose the SQL.
// Enable debug logging for the embedded DB layer:
// logging.level.com.alibaba.nacos.persistence.datasource=DEBUG
// Then inspect the actual count SQL and Derby error in logs.
// If tables are missing, reinitialize:
//   1. Stop Nacos
//   2. Remove {nacos.home}/data/derby-data
//   3. Restart Nacos (schema auto-creates)

// Cannot prevent a null count result purely client-side.
// Can pre-check that the embedded Derby data directory exists:
java.nio.file.Path derbyDir = Paths.get(nacosHome, "data", "derby-data");
if (!java.nio.file.Files.exists(derbyDir)) {
    throw new IllegalStateException("Embedded Derby data directory not found");
}

public static boolean isEmbeddedSchemaInitialized(Path nacosHome) {
    return Files.exists(nacosHome.resolve("data/derby-data/nacos"));
}

try {
    Page<E> page = paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);
} catch (IllegalArgumentException e) {
    if ("fetchPageLimit error".equals(e.getMessage())) {
        logger.error("Count query returned null — check embedded Derby schema", e);
        throw new IllegalStateException("Auth database schema issue", e);
    }
    throw e;
}

When it happens

Trigger: The sqlCountRows query references a table or column that does not exist in the embedded Derby schema, or the query has a syntax error that causes Derby to return no scalar result. This can happen after a schema migration that didn't apply to the auth tables, or if a custom SQL template is misconfigured.

Common situations: Auth plugin schema not initialized (embedded Derby auth tables missing); corrupted Derby database file; incomplete upgrade where auth DDL wasn't applied; custom SQL count template references a renamed column.

Related errors

• pageNo and pageSize must be greater than zero
• fetchPageLimit error
• 500
• pageNo and pageSize must be greater than zero
• PARAMETER_VALIDATE_ERROR

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/5909315b5372a9f1. Report an issue: GitHub.