{"record":{"id":"90045ef10451f35f","repo":"redis/jedis","slug":"failed-to-initialize-aggregation-cursor","errorCode":null,"errorMessage":"Failed to initialize aggregation cursor","messagePattern":"Failed to initialize aggregation cursor","errorType":"exception","errorClass":"JedisException","httpStatus":null,"severity":"error","filePath":"src/main/java/redis/clients/jedis/search/aggr/AggregateIterator.java","lineNumber":213,"sourceCode":"        .build(rawReply);\n\n    cursorId = result.getCursorId();\n    return result;\n  }\n\n  /**\n   * Initializes the aggregation by executing the initial FT.AGGREGATE command.\n   */\n  private void initializeAggregation(AggregationBuilder aggregationBuilder) {\n    CommandArguments args = new CommandArguments(SearchProtocol.SearchCommand.AGGREGATE)\n        .add(indexName).addParams(aggregationBuilder);\n\n    try {\n      Object rawReply = executeCommand(args);\n      aggrCommandResult = AggregationResult.SEARCH_AGGREGATION_RESULT_WITH_CURSOR.build(rawReply);\n      cursorId = aggrCommandResult.getCursorId();\n    } catch (Exception e) {\n      throw new JedisException(\"Failed to initialize aggregation cursor\", e);\n    }\n  }\n\n  /**\n   * Executes a command using the connection entry. If the entry value is a Pool, borrows a\n   * connection, executes the command, and returns the connection to the pool. This pattern prevents\n   * connection pool exhaustion during long-running aggregation operations.\n   */\n  @SuppressWarnings(\"unchecked\")\n  private Object executeCommand(CommandArguments args) {\n    Object entryValue = connectionEntry.getValue();\n\n    if (entryValue instanceof Connection) {\n      // Direct connection (non-pooled) - use directly\n      return ((Connection) entryValue).executeCommand(args);\n    } else if (entryValue instanceof Pool) {\n      // Pooled connection - borrow, use, and return\n      try (Connection conn = ((Pool<Connection>) entryValue).getResource()) {","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/redis/jedis/blob/6dac31d4c224fb3257c216f3985340c6f500cdcb/src/main/java/redis/clients/jedis/search/aggr/AggregateIterator.java#L195-L231","documentation":"Wraps failures from the initial FT.AGGREGATE ... WITHCURSOR invocation in initializeAggregation. If the command cannot be executed (connectivity, auth, bad index, malformed arguments) or the reply cannot be built into an AggregationResult with cursor, this JedisException is thrown during iterator construction.","triggerScenarios":"Creating AggregateIterator when the index does not exist, credentials are wrong, the connection cannot be established, or the aggregation builder produces arguments the server rejects.","commonSituations":"Typo in index name; FT.AGGREGATE unavailable (RediSearch module not loaded); ACL denying the user the aggregate command; network misconfiguration to the selected shard.","solutions":["Verify the search index exists (FT.INFO indexName) and the RediSearch module is loaded","Check credentials/ACL permissions for FT.AGGREGATE","Test connectivity to the shard with a simple PING/FT._LIST before iterating","Catch JedisException at construction and inspect the cause for the server-side error message"],"exampleFix":"// before\nAggregateIterator it = new AggregateIterator(provider, \"idx\", aggr); // throws on bad index\n// after\ntry {\n  AggregateIterator it = new AggregateIterator(provider, \"idx\", aggr);\n} catch (JedisException e) {\n  log.error(\"Aggregation init failed: {}\", e.getCause() == null ? e : e.getCause().getMessage());\n}","handlingStrategy":"try-catch","validationCode":"// pre-checks before constructing the iterator\ntry (Jedis j = pool.getResource()) { j.ping(); }\n// and verify the index exists:\n// provider-level FT.INFO indexName must succeed","typeGuard":"null","tryCatchPattern":"try {\n  AggregateIterator it = new AggregateIterator(provider, indexName, aggr);\n} catch (JedisException e) {\n  // init failed: bad index, auth/ACL, module missing, or connectivity\n  log.error(\"Aggregation init failed\", e.getCause());\n}","preventionTips":["Verify the index exists with FT.INFO before aggregating","Confirm RediSearch module is loaded and the user's ACL allows FT.AGGREGATE","Smoke-test connectivity to the target shard before heavy queries","Include the index name and cause in application error logs"],"tags":["jedis","search","aggregation","cursor","initialization"],"backgroundTag":"api-request-failed","analyzedSha":"6dac31d4c224fb3257c216f3985340c6f500cdcb","analyzedAt":"2026-09-08T04:55:01.204Z","contentChangedAt":"2026-09-08T04:55:01.204Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}