What causes "Build directory unknown to gradle: {}" in elastic/elasticsearch?

Verify the offending directory dependency is a legitimate Gradle project output; if so, ensure its build dir is included in getProjectBuildDirs() passed to the SplitPackagesAuditTask parameters.

elastic/elasticsearch · error · IllegalStateException

Build directory unknown to gradle: {}

Error message

Build directory unknown to gradle: {}

What it means

Thrown by SplitPackagesAuditTask.formatDependency while walking parent directories of a directory-valued dependency file looking for a directory literally named 'build'. Once found, it looks that build dir up in the projectBuildDirs map (File -> project path); if the map has no entry the lookup returns null and the task throws because it cannot attribute the dependency to a Gradle project.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/precommit/SplitPackagesAuditTask.java:350

            }
        }

        private static String getPackageName(Path path) {
            List<String> subpackages = new ArrayList<>();
            for (int i = 0; i < path.getNameCount() - 1; ++i) {
                subpackages.add(path.getName(i).toString());
            }
            return String.join(".", subpackages);
        }

        private String formatDependency(File dependencyFile) {
            if (dependencyFile.isDirectory()) {
                while (dependencyFile.getName().equals("build") == false) {
                    dependencyFile = dependencyFile.getParentFile();
                }
                String projectName = getParameters().getProjectBuildDirs().get().get(dependencyFile);
                if (projectName == null) {
                    throw new IllegalStateException("Build directory unknown to gradle: " + dependencyFile);
                }
                return "project " + projectName;
            }
            return dependencyFile.getName(); // just the jar filename
        }
    }

    interface Parameters extends WorkParameters {
        Property<String> getProjectPath();

        MapProperty<File, String> getProjectBuildDirs();

        ConfigurableFileCollection getClasspath();

        SetProperty<File> getSrcDirs();

        SetProperty<String> getIgnoreClasses();

View on GitHub (pinned to db6a809a66)

Solutions

Verify the offending directory dependency is a legitimate Gradle project output; if so, ensure its build dir is included in getProjectBuildDirs() passed to the SplitPackagesAuditTask parameters.
If the directory is an external/non-project classpath root, convert it to a jar or exclude it from the audit input configuration.
Run with --debug and inspect the formatDependency call to see which directory triggered the null lookup, then trace it back to the configuration that supplied it.

Defensive patterns

Strategy: validation

Validate before calling

// Before running, ensure every directory dependency maps to a known project build dir
Map<File,String> projectBuildDirs = parameters.getProjectBuildDirs().get();
for (File dep : directoryDependencies) {
    File buildRoot = findAncestorNamed(dep, "build");
    if (buildRoot == null || projectBuildDirs.containsKey(buildRoot) == false) {
        throw new IllegalStateException("Directory dependency not registered: " + dep);
    }
}

Prevention

Keep directory-valued classpath entries limited to standard Gradle project outputs.
When adding composite builds, wire their build dirs into the audit's projectBuildDirs parameter.
Avoid external source trees that coincidentally contain a 'build' folder.

When it happens

Trigger: A dependency file is a directory (not a jar), so formatDependency walks up until it finds a parent named 'build', but that build directory was not registered in the task's projectBuildDirs parameter. This happens when a directory dependency lives outside the set of known project build outputs or under a 'build' folder that is not the canonical project build dir.

Common situations: A composite/included build whose build dir isn't passed to the audit's projectBuildDirs map; a directory dependency pointing at an external/unmanaged source tree that happens to contain a 'build' folder; cross-project classpath entries added via custom configurations that bypass the standard project output wiring.

Related errors

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