What causes "Number of nodes should be >= 1 but was {} for {}" in elastic/elasticsearch?

Pass a positive integer: setNumberOfNodes(3) or numberOfNodes = 3 in the testClusters DSL.

elastic/elasticsearch · error · IllegalArgumentException

Number of nodes should be >= 1 but was {} for {}

Error message

Number of nodes should be >= 1 but was {} for {}

What it means

Thrown by ElasticsearchCluster.setNumberOfNodes when the requested node count is less than 1. A test cluster must have at least one node, so the guard rejects zero or negative inputs before mutating the node list.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/testclusters/ElasticsearchCluster.java:173

        this.shared = shared;
    }

    @Classpath
    public FileCollection getInstalledClasspath() {
        return pluginAndModuleConfiguration.getAsFileTree().filter(f -> f.getName().endsWith(".jar"));
    }

    @InputFiles
    @PathSensitive(PathSensitivity.RELATIVE)
    public FileCollection getInstalledFiles() {
        return pluginAndModuleConfiguration.getAsFileTree().filter(f -> f.getName().endsWith(".jar") == false);
    }

    public void setNumberOfNodes(int numberOfNodes) {
        checkFrozen();

        if (numberOfNodes < 1) {
            throw new IllegalArgumentException("Number of nodes should be >= 1 but was " + numberOfNodes + " for " + this);
        }

        if (numberOfNodes < nodes.size()) {
            throw new IllegalArgumentException(
                "Cannot shrink " + this + " to have " + numberOfNodes + " nodes as it already has " + getNumberOfNodes()
            );
        }

        for (int i = nodes.size(); i < numberOfNodes; i++) {
            this.nodes.add(
                new ElasticsearchNode(
                    safeName(clusterName),
                    path,
                    clusterName + "-" + i,
                    project,
                    reaper,
                    testClustersRegistryProvider,
                    fileSystemOperations,

View on GitHub (pinned to db6a809a66)

Solutions

Pass a positive integer: setNumberOfNodes(3) or numberOfNodes = 3 in the testClusters DSL.
If the value comes from a property, coerce and validate it: `Math.max(1, (project.findProperty('numNodes') ?: '1') as int)`.
Check the calling Gradle DSL block (testClusters { node {}) — make sure numberOfNodes is set, not left at 0.

Example fix

// before
testClusters {
  numberOfNodes = (project.findProperty('numNodes') ?: 0) as int
}

// after
testClusters {
  numberOfNodes = Math.max(1, (project.findProperty('numNodes') ?: '1') as int)
}

Defensive patterns

Strategy: validation

Validate before calling

int n = requestedNodeCount;
if (n < 1) {
    throw new IllegalArgumentException("numberOfNodes must be >= 1, got " + n);
}
cluster.setNumberOfNodes(n);

Prevention

Coerce user-supplied node counts with Math.max(1, value).
Default test cluster size flags to a positive integer (e.g. '1').
Validate parameters at the point of input, not deep in the build.

When it happens

Trigger: Calling setNumberOfNodes(0) or setNumberOfNodes(-n) on an ElasticsearchCluster (the Gradle test-cluster DSL), or wiring numberOfNodes from a property that resolves to <=0.

Common situations: Reading numberOfNodes from a -Ptest.numNodes flag or env var that defaults to 0 when unset; parameterizing tests with a node-count expression that underflows; copy-paste of a config block missing the count.

Related errors

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