{"record":{"id":"718d6160897ebd43","repo":"alibaba/nacos","slug":"fetchpagelimit-error-718d61","errorCode":null,"errorMessage":"fetchPageLimit error","messagePattern":"fetchPageLimit error","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/persistence/extrnal/AuthExternalPaginationHelperImpl.java","lineNumber":78,"sourceCode":"    @Override\n    public Page<E> fetchPage(final String sqlCountRows, final String sqlFetchRows,\n        final Object[] args,\n        final int pageNo, final int pageSize, final RowMapper rowMapper) {\n        return fetchPage(sqlCountRows, sqlFetchRows, args, pageNo, pageSize, null, rowMapper);\n    }\n    \n    @Override\n    public Page<E> fetchPage(final String sqlCountRows, final String sqlFetchRows, Object[] args,\n        final int pageNo,\n        final int pageSize, final Long lastMaxId, final RowMapper rowMapper) {\n        if (pageNo <= 0 || pageSize <= 0) {\n            throw new IllegalArgumentException(\"pageNo and pageSize must be greater than zero\");\n        }\n        \n        // Query the total number of current records.\n        Integer rowCountInt = jdbcTemplate.queryForObject(sqlCountRows, args, Integer.class);\n        if (rowCountInt == null) {\n            throw new IllegalArgumentException(\"fetchPageLimit error\");\n        }\n        \n        // Compute pages count\n        int pageCount = rowCountInt / pageSize;\n        if (rowCountInt > pageSize * pageCount) {\n            pageCount++;\n        }\n        \n        // Create Page object\n        final Page<E> page = new Page<>();\n        page.setPageNumber(pageNo);\n        page.setPagesAvailable(pageCount);\n        page.setTotalCount(rowCountInt);\n        \n        if (pageNo > pageCount) {\n            return page;\n        }\n        ","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/persistence/extrnal/AuthExternalPaginationHelperImpl.java#L60-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check server logs for the preceding SQL/database exception.","Verify the external database has the auth tables created (users, roles, permissions, role_permissions).","Run the Nacos schema initialization SQL (nacos-mysql.sql or equivalent) against the external database.","Confirm the JDBC connection URL points to the correct database/schema."],"exampleFix":"// Not a code fix — initialize the external DB schema.\n// Run the Nacos MySQL initialization script:\n//   mysql -u root -p nacos < conf/mysql-schema.sql\n// Verify tables exist:\n//   SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'nacos';\n// Ensure JDBC URL in application.properties points to the right database.","handlingStrategy":"try-catch","validationCode":"// Cannot prevent null count purely at the API level.\n// Pre-check that the external DB schema is initialized:\nInteger tableCount = jdbcTemplate.queryForObject(\n    \"SELECT COUNT(*) FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'nacos'\", Integer.class);\nif (tableCount == null || tableCount == 0) {\n    throw new IllegalStateException(\"Nacos schema not initialized in external DB\");\n}","typeGuard":"public static boolean isExternalSchemaReady(JdbcTemplate jdbc) {\n    try {\n        Integer c = jdbc.queryForObject(\n            \"SELECT COUNT(*) FROM users\", Integer.class);\n        return c != null;\n    } catch (Exception e) {\n        return false;\n    }\n}","tryCatchPattern":"try {\n    Page<E> page = paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);\n} catch (IllegalArgumentException e) {\n    if (\"fetchPageLimit error\".equals(e.getMessage())) {\n        logger.error(\"Count query returned null — external DB schema issue\", e);\n        throw new IllegalStateException(\"External database schema not initialized\", e);\n    }\n    throw e;\n}","preventionTips":["Run the Nacos schema initialization SQL (conf/mysql-schema.sql) before first startup with an external DB.","Verify the JDBC connection URL points to the correct database with auth tables.","Include a schema-verification step in deployment scripts.","Monitor startup logs for SQL errors during auth module initialization."],"tags":["pagination","external-db","auth-plugin","mysql","postgresql","database-error","sql","schema"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}