elastic/elasticsearch · error · InvalidUserDataException

Branch {branch} already exists

Error message

Branch {branch} already exists

What it means

Thrown by UpdateBranchesJsonTask.executeTask() in the addBranch path when a branch with the same name already exists in branches.json. Addition is rejected to avoid duplicate entries.

Source

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

        String[] parts = branchAndVersion.split(":");
        if (parts.length != 2) {
            throw new InvalidUserDataException("Expected branch and version in format <branch>:<version>");
        }
        return new DevelopmentBranch(parts[0], Version.fromString(parts[1]));
    }

    @TaskAction
    public void executeTask() throws IOException {
        List<DevelopmentBranch> developmentBranches = readBranches(branchesFile);

        if (addBranch == null && removeBranch == null && updateBranch == null) {
            throw new InvalidUserDataException("At least one of add-branch, remove-branch or update-branch must be specified");
        }

        if (addBranch != null) {
            LOGGER.info("Adding branch {} with version {}", addBranch.name(), addBranch.version());
            if (developmentBranches.stream().anyMatch(developmentBranch -> developmentBranch.name().equals(addBranch.name()))) {
                throw new InvalidUserDataException("Branch " + addBranch.name() + " already exists");
            }
            developmentBranches.add(addBranch);
        }
        if (removeBranch != null) {
            LOGGER.info("Removing branch {}", removeBranch);
            if (developmentBranches.stream().noneMatch(developmentBranch -> developmentBranch.name().equals(removeBranch))) {
                throw new InvalidUserDataException("Branch " + removeBranch + " does not exist");
            }
            developmentBranches.removeIf(developmentBranch -> developmentBranch.name().equals(removeBranch));
        }
        if (updateBranch != null) {
            LOGGER.info("Updating branch {} with version {}", updateBranch.name(), updateBranch.version());
            if (developmentBranches.stream().noneMatch(developmentBranch -> developmentBranch.name().equals(updateBranch.name()))) {
                throw new InvalidUserDataException("Branch " + updateBranch.name() + " does not exist");
            }
            developmentBranches.removeIf(developmentBranch -> developmentBranch.name().equals(updateBranch.name()));
            developmentBranches.add(updateBranch);
        }

View on GitHub (pinned to db6a809a66)

Solutions

1. If you intended to change the version of an existing branch, use --update-branch=<name>:<version> instead of --add-branch.
2. If the existing entry is wrong, first --remove-branch=<name>, then --add-branch.
3. Verify the current contents of branches.json before adding.

Example fix

// before
./gradlew updateBranches --add-branch=8.10:8.10.1   # 8.10 already present

// after
./gradlew updateBranches --update-branch=8.10:8.10.1

// Read branches.json and check for an existing branch before adding
static boolean branchExists(Path branchesFile, String name) throws IOException {
    return new ObjectMapper().readTree(branchesFile.toFile())
        .path("branches").findValuesAsText("branch").contains(name);
}
// only call --add-branch when branchExists(...) is false

When it happens

Trigger: Running --add-branch=<name>:<version> for a branch name that is already listed in branches.json.

Common situations: Re-running an add step that partially completed; the branch was created by another process; an operator did not realise the branch already existed.

Related errors

• Branch {branch} does not exist
• File branches.json has not been found in {path}
• Release version not specified
• No version tags specified
• Unknown version type {key}

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