elastic/elasticsearch · error · UncheckedIOException

Failed to read branches.json from: {}

Error message

Failed to read branches.json from: {}

What it means

Thrown by GlobalBuildInfoPlugin.getDevelopmentBranches() when reading branches.json from a local file path fails. This path is taken when branchesFileLocation does not start with http:// or https:// (i.e., it is a local file path). Files.readAllBytes throws IOException, which is wrapped in UncheckedIOException.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/info/GlobalBuildInfoPlugin.java:254

                        + "]. Either disable offline mode, set -P"
                        + BRANCHES_FILE_LOCATION_PROPERTY
                        + "=<local file path>, or create branches.json at the workspace root."
                );
            }
        }
        LOGGER.info("Reading branches.json from {}", branchesFileLocation);
        byte[] branchesBytes;
        if (isHttpLocation(branchesFileLocation)) {
            try {
                branchesBytes = HttpUtils.readHttpBytesWithRetry(branchesFileLocation);
            } catch (IOException e) {
                throw new UncheckedIOException("Failed to download branches.json from: " + branchesFileLocation, e);
            }
        } else {
            try {
                branchesBytes = Files.readAllBytes(new File(branchesFileLocation).toPath());
            } catch (IOException e) {
                throw new UncheckedIOException("Failed to read branches.json from: " + branchesFileLocation, e);
            }
        }

        var branchesFileParser = new BranchesFileParser(new ObjectMapper());
        return branchesFileParser.parse(branchesBytes);
    }

    private static boolean isHttpLocation(String branchesFileLocation) {
        return branchesFileLocation.startsWith("http://") || branchesFileLocation.startsWith("https://");
    }

    private void logGlobalBuildInfo(BuildParameterExtension buildParams) {
        final String osName = System.getProperty("os.name");
        final String osVersion = System.getProperty("os.version");
        final String osArch = System.getProperty("os.arch");
        final Jvm gradleJvm = Jvm.current();
        JvmInstallationMetadata gradleJvmMetadata = metadataDetector.getMetadata(getJavaInstallation(gradleJvm.getJavaHome()));
        final String gradleJvmVendorDetails = gradleJvmMetadata.getVendor().getDisplayName();

View on GitHub (pinned to db6a809a66)

Solutions

1. Verify the file path is correct and readable: test -r <path> && echo readable.
2. If the file is a symlink, ensure the target exists: readlink -f <path>.
3. Recreate the file from a known-good source.
4. Check file permissions: chmod +r <path> if the Gradle daemon process cannot read it.

Example fix

# before
./gradlew build -Pbranches.file.location=/home/user/branch.json  # typo: branch vs branches

# after
./gradlew build -Pbranches.file.location=/home/user/branches.json

// Validate local branches.json path before reading
File f = new File(branchesFileLocation);
if (!f.exists()) {
    throw new GradleException("branches.json not found at: " + branchesFileLocation);
}
if (!f.canRead()) {
    throw new GradleException("branches.json is not readable: " + branchesFileLocation);
}

When it happens

Trigger: branchesFileLocation is a local path (set via -Pbranches.file.location=<path> or resolved from the offline-mode fallback to workspace-root/branches.json). The file exists (otherwise a different error may surface from the file-not-found IOException) but cannot be read, or the path is invalid. Files.readAllBytes throws IOException for permission denied, truncated file, or I/O errors.

Common situations: The user passes -Pbranches.file.location to a path that exists but is unreadable (permissions). The local branches.json at the workspace root is corrupted or partially written. A stale or broken symlink exists at the branches.json location.

Related errors

• Failed to read {exclusionsFileAbsolutePath}
• Failed to parse content of branches.json
• Unable to create reaper JAR output directory {}
• Failed to write unicast_hosts for {}
• Failed to create working directory for {}, with: {}

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