elastic/elasticsearch · error · TestClustersException

Can't run bin script: `{}` does not exist. Is this the distr

Error message

Can't run bin script: `{}` does not exist. Is this the distribution you expect it to be ?

What it means

Thrown by runElasticsearchBinScriptWithInput before exec when neither <distro>/bin/<tool> nor <distro>/bin/<tool>.bat exists. The node refuses to invoke a bin script that is not part of the unpacked distribution. The message prompts the developer to question the distribution choice because the most common root cause is selecting a distribution variant that does not ship the requested tool.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/testclusters/ElasticsearchNode.java:775

    @Override
    public void rolesFile(File rolesYml) {
        roleFiles.add(rolesYml);
    }

    @Override
    public void requiresFeature(String feature, Version from) {
        featureFlags.add(new FeatureFlag(feature, from, null));
    }

    @Override
    public void requiresFeature(String feature, Version from, Version until) {
        featureFlags.add(new FeatureFlag(feature, from, until));
    }

    private void runElasticsearchBinScriptWithInput(String input, String tool, CharSequence... args) {
        if (Files.exists(getDistroDir().resolve("bin").resolve(tool)) == false
            && Files.exists(getDistroDir().resolve("bin").resolve(tool + ".bat")) == false) {
            throw new TestClustersException(
                "Can't run bin script: `" + tool + "` does not exist. " + "Is this the distribution you expect it to be ?"
            );
        }
        try (InputStream byteArrayInputStream = new ByteArrayInputStream(input.getBytes(StandardCharsets.UTF_8))) {
            LoggedExec.exec(execOperations, spec -> {
                spec.setEnvironment(getESEnvironment());
                spec.workingDir(getDistroDir());
                spec.executable(OS.conditionalString().onUnix(() -> "./bin/" + tool).onWindows(() -> "cmd").supply());
                spec.args(OS.<List<CharSequence>>conditional().onWindows(() -> {
                    ArrayList<CharSequence> result = new ArrayList<>();
                    result.add("/c");
                    result.add("bin\\" + tool + ".bat");
                    Collections.addAll(result, args);
                    return result;
                }).onUnix(() -> Arrays.asList(args)).supply());
                spec.setStandardInput(byteArrayInputStream);

            });

View on GitHub (pinned to db6a809a66)

Solutions

Switch to a distribution variant that ships the tool (e.g. the default/x-pack distribution rather than 'bare' when you need elasticsearch-users).
For BWC across 6.3.0, the code already picks the right tool name; if you bypass it, mirror that logic.
Verify <distro>/bin/ on disk (ls build/testclusters/<node>/<distro>/bin/) and clean/re-extract if bin/ is missing.
Confirm the version string matches a real ES release; a malformed version can select a wrong distro.

Example fix

// before: bare distro lacks elasticsearch-users
testClusters {
  n { distribution 'bare', '8.15.0'; user([:]) }
}
// after: default distro ships x-pack tooling
testClusters {
  n { distribution 'default', '8.15.0'; user([:]) }
}

Defensive patterns

Strategy: validation

Validate before calling

static void ensureBinToolExists(Path distroDir, String tool) {
    boolean ok = Files.exists(distroDir.resolve("bin").resolve(tool))
             || Files.exists(distroDir.resolve("bin").resolve(tool + ".bat"));
    if (!ok) {
        throw new IllegalStateException("Distribution " + distroDir
            + " does not provide bin/" + tool + "; pick a distribution variant that ships it.");
    }
}
// Use: ensureBinToolExists(node.getDistroDir(), "elasticsearch-users");

Prevention

Use the default/x-pack distribution when you need elasticsearch-users or elasticsearch-keystore.
For BWC across 6.3.0, rely on the built-in tool-name selection.
Verify bin/ contents after extraction.

When it happens

Trigger: Invoking (directly or via start()) a tool like 'elasticsearch-keystore', 'elasticsearch-plugin', or 'elasticsearch-users' on a distribution that does not contain it. Happens with the 'bare' minimal distribution (no x-pack), old versions that named scripts differently (e.g. 'x-pack/users' pre-6.3 vs 'elasticsearch-users' post-6.3), or a custom/ corrupt distro missing bin/.

Common situations: Using a distribution type that omits x-pack while the test calls elasticsearch-users. BWC test running against a version that uses the old script name. Plugin installed on a distribution where elasticsearch-plugin was renamed. Distribution partially extracted and bin/ missing.

Related errors

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