elastic/elasticsearch · error · GradleException

Task {} is not configured to use any clusters. Be sure to ca

Error message

Task {} is not configured to use any clusters. Be sure to call useCluster().

What it means

Thrown by RunTask.runAndWait() at task-execution time when the `useCluster(...)` method was never called on the task, so `getClusters()` is empty. RunTask is a `@TaskAction` that must stream logs from at least one ElasticsearchCluster node; with no clusters registered there is nothing to run and the build aborts. This is a configuration-time defect surfaced at execution time, not an environment failure.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/testclusters/RunTask.java:360

                }

            }
        }
        if (debug) {
            enableDebug();
        }
        if (cliDebug) {
            enableCliDebug();
        }
    }

    @TaskAction
    public void runAndWait() throws IOException {
        List<BufferedReader> toRead = new ArrayList<>();
        List<BooleanSupplier> aliveChecks = new ArrayList<>();

        if (getClusters().isEmpty()) {
            throw new GradleException("Task " + getPath() + " is not configured to use any clusters. Be sure to call useCluster().");
        }

        try {
            for (ElasticsearchCluster cluster : getClusters()) {
                cluster.writeUnicastHostsFiles();
                for (ElasticsearchNode node : cluster.getNodes()) {
                    BufferedReader reader = Files.newBufferedReader(node.getEsOutputFile());
                    toRead.add(reader);
                    aliveChecks.add(node::isProcessAlive);
                }
            }

            while (Thread.currentThread().isInterrupted() == false) {
                boolean readData = false;
                for (BufferedReader bufferedReader : toRead) {
                    if (bufferedReader.ready()) {
                        readData = true;
                        logger.lifecycle(bufferedReader.readLine());

View on GitHub (pinned to db6a809a66)

Solutions

In the task configuration block, call `useCluster(testClusters.<name>)` so the task is bound to a declared `ElasticsearchCluster`.
Verify the cluster is declared in the same project (cross-project use throws a different error, #110) and that its name matches the task or is referenced explicitly.
If subclassing RunTask, ensure super-configuration or an explicit `useCluster` call runs; do not rely on lazy providers that may never resolve before execution.
Run `./gradlew <task> --info` and confirm `getClusters()` is populated before the `@TaskAction` fires.

Example fix

// before
run {
  // cluster declared but never wired
}
// after
run {
  useCluster(testClusters.myCluster)
}

Defensive patterns

Strategy: validation

Validate before calling

// Before depending on this task, assert a cluster is wired
if (task.getClusters().isEmpty()) {
  throw new GradleException("Configure useCluster(...) on " + task.getPath());
}

Prevention

Treat `useCluster(...)` as a mandatory call in any RunTask configuration block; add a lint check in a convention plugin.
When refactoring cluster declarations, grep for `useCluster(` references that point at the old name and update them.
Add a `doFirst { assert !getClusters().isEmpty() }` guard to fail with a clearer message before the @TaskAction.

When it happens

Trigger: Invoking a `RunTask` (e.g. a task of type `elasticsearch.testclusters.run` / a custom `run` task) whose build script never called `task.useCluster(cluster)`. Also happens when the cluster property is wired via a Provider that resolved to empty, or when a subclass overrode configuration hooks and skipped the registration.

Common situations: A developer copies a `run { ... }` block from another project but forgets the `useCluster(...)` line; refactoring a test that used `ESIntegTestCase` into a standalone run task; renaming a cluster property so `useCluster(oldName)` silently no-ops because the reference was never reified.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/c6d6d247fb4eb22c. Report an issue: GitHub.