alibaba/nacos · error · IllegalArgumentException

fetchPageLimit error

Error message

fetchPageLimit error

What it means

Thrown by AuthExternalPaginationHelperImpl.fetchPage when the SQL count query via jdbcTemplate.queryForObject returns null. This means the external database (MySQL/PostgreSQL) returned no result for the count query. The generic message 'fetchPageLimit error' does not expose the underlying SQL or database error.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/persistence/extrnal/AuthExternalPaginationHelperImpl.java:78

    @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 = jdbcTemplate.queryForObject(sqlCountRows, args, Integer.class);
        if (rowCountInt == null) {
            throw new IllegalArgumentException("fetchPageLimit error");
        }
        
        // Compute pages count
        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 server logs for the preceding SQL/database exception.
2. Verify the external database has the auth tables created (users, roles, permissions, role_permissions).
3. Run the Nacos schema initialization SQL (nacos-mysql.sql or equivalent) against the external database.
4. Confirm the JDBC connection URL points to the correct database/schema.

Example fix

// Not a code fix — initialize the external DB schema.
// Run the Nacos MySQL initialization script:
//   mysql -u root -p nacos < conf/mysql-schema.sql
// Verify tables exist:
//   SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'nacos';
// Ensure JDBC URL in application.properties points to the right database.

// Cannot prevent null count purely at the API level.
// Pre-check that the external DB schema is initialized:
Integer tableCount = jdbcTemplate.queryForObject(
    "SELECT COUNT(*) FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'nacos'", Integer.class);
if (tableCount == null || tableCount == 0) {
    throw new IllegalStateException("Nacos schema not initialized in external DB");
}

public static boolean isExternalSchemaReady(JdbcTemplate jdbc) {
    try {
        Integer c = jdbc.queryForObject(
            "SELECT COUNT(*) FROM users", Integer.class);
        return c != null;
    } catch (Exception e) {
        return false;
    }
}

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 — external DB schema issue", e);
        throw new IllegalStateException("External database schema not initialized", e);
    }
    throw e;
}

When it happens

Trigger: The count SQL references a table or column that does not exist in the external database schema, or the query has a syntax error. Since queryForObject returns null rather than throwing when no rows match, this can also indicate the auth tables are empty or not yet created in the external DB.

Common situations: External database schema not initialized (auth tables not created); database connection points to wrong schema/database; partial migration leaving auth tables missing; custom SQL count template references a non-existent column after a schema change.

Related errors

• pageNo and pageSize must be greater than zero
• fetchPageLimit error
• pageNo and pageSize must be greater than zero
• AgentVersionContent kind must be {AgentVersionContent.KIND}
• Unknown {objectName} field: {field}

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