elastic/elasticsearch · error · GradleException

Gradle is running in offline mode, but branches.json locatio

Error message

Gradle is running in offline mode, but branches.json location [{configuredBranchesFileLocation}] is an http(s) URL and no local branches.json was found at [{localBranchesFile}]. Either disable offline mode, set -P{BRANCHES_FILE_LOCATION_PROPERTY}=<local file path>, or create branches.json at the workspace root.

What it means

Thrown by GlobalBuildInfoPlugin.getDevelopmentBranches() when Gradle is in offline mode (--offline), the branches.json location is an http(s) URL (the default DEFAULT_BRANCHES_FILE_URL or a user-configured URL via the branches.file.location Gradle property), and no local branches.json file exists at the workspace root. This is a hard failure because the build cannot proceed without branch information in offline mode.

Source

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

            .toList();
    }

    private List<DevelopmentBranch> getDevelopmentBranches() {
        String configuredBranchesFileLocation = project.getProviders()
            .gradleProperty(BRANCHES_FILE_LOCATION_PROPERTY)
            .getOrElse(DEFAULT_BRANCHES_FILE_URL);
        String branchesFileLocation = configuredBranchesFileLocation;
        if (project.getGradle().getStartParameter().isOffline() && isHttpLocation(configuredBranchesFileLocation)) {
            File localBranchesFile = new File(Util.locateElasticsearchWorkspace(project.getGradle()), "branches.json");
            if (localBranchesFile.exists()) {
                LOGGER.warn(
                    "Gradle is running in offline mode; using local branches.json at [{}] instead of downloading from [{}].",
                    localBranchesFile,
                    configuredBranchesFileLocation
                );
                branchesFileLocation = localBranchesFile.getAbsolutePath();
            } else {
                throw new GradleException(
                    "Gradle is running in offline mode, but branches.json location ["
                        + configuredBranchesFileLocation
                        + "] is an http(s) URL and no local branches.json was found at ["
                        + localBranchesFile
                        + "]. 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);
            }

View on GitHub (pinned to db6a809a66)

Solutions

Place a branches.json file at the root of the Elasticsearch workspace.
Pass a local file path: ./gradlew build --offline -Pbranches.file.location=/path/to/local/branches.json.
Remove the --offline flag if network access is available.
Download branches.json from the default URL once and commit or cache it at the workspace root for offline use.

Example fix

# before
./gradlew build --offline  # no branches.json at workspace root

# after (option 1: local file)
curl -o branches.json https://.../branches.json
./gradlew build --offline

# after (option 2: explicit local path)
./gradlew build --offline -Pbranches.file.location=/home/user/branches.json

Defensive patterns

Strategy: fallback

Validate before calling

// Check offline mode and branches.json before building
boolean offline = gradle.getStartParameter().isOffline();
File localBranches = new File(workspaceDir, "branches.json");
if (offline && !localBranches.exists()) {
    throw new GradleException("Offline mode requires branches.json at workspace root or -Pbranches.file.location=<local path>");
}

Prevention

Place a branches.json at the workspace root for offline builds.
Use -Pbranches.file.location=<local path> to point to a local copy.
Only use --offline when you have all required local files cached.

When it happens

Trigger: Gradle is started with --offline flag. The branches.file.location Gradle property is not set or is set to an http(s) URL. No branches.json file exists at Util.locateElasticsearchWorkspace(gradle)/branches.json. All three conditions must be true simultaneously.

Common situations: A developer runs ./gradlew build --offline on a plane or behind a firewall. CI agents in an air-gapped environment use --offline but branches.json was never placed at the workspace root. The default URL changed and no local copy was cached.

Related errors

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