What causes "File branches.json has not been found in {path}" in elastic/elasticsearch?

Confirm branches.json exists at the expected location (typically the project root / docs resources).

elastic/elasticsearch · error · InvalidUserDataException

File branches.json has not been found in {path}

Error message

File branches.json has not been found in {path}

What it means

Thrown by UpdateBranchesJsonTask.readBranches() when branchesFile does not exist or is not a regular file. The task cannot read or modify branches.json without it.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/UpdateBranchesJsonTask.java:166

        JsonNode jsonNode = objectMapper.readTree(new FileInputStream(branchesFile));
        ArrayNode updatedBranches = objectMapper.createArrayNode();
        for (DevelopmentBranch branch : developmentBranches) {
            ObjectNode objectNode = objectMapper.createObjectNode();
            objectNode.put("branch", branch.name());
            objectNode.put("version", branch.version().toString());
            updatedBranches.add(objectNode);
        }
        ((ObjectNode) jsonNode).replace("branches", updatedBranches);

        DefaultPrettyPrinter prettyPrinter = new DefaultPrettyPrinter();
        prettyPrinter.indentArraysWith(new DefaultIndenter("  ", DefaultIndenter.SYS_LF));
        objectMapper.writer(prettyPrinter).writeValue(branchesFile, jsonNode);
    }

    private List<DevelopmentBranch> readBranches(File branchesFile) {
        if (branchesFile.isFile() == false) {
            throw new InvalidUserDataException("File branches.json has not been found in " + branchesFile.getAbsolutePath());
        }

        try {
            byte[] branchesBytes = Files.readAllBytes(branchesFile.toPath());
            return branchesFileParser.parse(branchesBytes);
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to read branches.json from " + branchesFile.getPath(), e);
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

Confirm branches.json exists at the expected location (typically the project root / docs resources).
Run the Gradle invocation from the repository root so the relative path resolves.
Restore branches.json from git if it was deleted.

Defensive patterns

Strategy: validation

Validate before calling

// Verify branches.json resolves to a file before running the task
Path branches = rootDir.resolve("branches.json");
if (!Files.isRegularFile(branches)) {
    throw new GradleException("branches.json missing at " + branches);
}

Prevention

Run release tasks from the repository root.
Treat branches.json as a tracked artifact; never delete it.

When it happens

Trigger: The configured branchesFile path does not resolve to an existing file — wrong working directory, the file was deleted, or the path property was never set correctly.

Common situations: Running the task from the wrong working directory; branches.json was never created in this checkout; the path was overridden by a misconfigured property.

Related errors

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