elastic/elasticsearch · error · IllegalArgumentException

Cannot use a commit SHA ({branchRef}) as --branch when fetch

Error message

Cannot use a commit SHA ({branchRef}) as --branch when fetching external changelog sources: git fetch on the remote repository requires a branch or tag name. Local Elasticsearch changelog YAML can still be checked out from a SHA; pass a named branch for --branch (and use --bc-ref for the build candidate when applicable).

What it means

Thrown by BundleChangelogsTask.normalizeBranchForExternalFetch when the --branch value looks like a raw commit SHA (matched by isShaRef). External repositories cannot be fetched by SHA via `git fetch <url> <sha>` (git requires a named ref), so the task rejects SHAs early and instructs the user to pass a named branch for --branch and use --bc-ref for a build-candidate SHA.

Source

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

    /**
     * Normalizes a branch reference for use with external repos. Strips known
     * remote prefixes ({@code upstream/}, {@code origin/}) which are ES-repo-specific,
     * and when {@code esUpstreamRemote} is set, strips {@code <remote>/} for the
     * Elasticsearch remote name returned by {@link GitWrapper#getUpstream()} (e.g.
     * {@code elastic/main} → {@code main}) so {@code git fetch} targets a branch that
     * exists on the external repository.
     * <p>
     * Raw commit SHAs are rejected since they are meaningless for external repositories.
     * Other refs (including branch names with slashes like {@code feature/foo}) are passed
     * through except for the prefixes above.
     */
    static String normalizeBranchForExternalFetch(String branchRef) {
        return normalizeBranchForExternalFetch(branchRef, null);
    }

    static String normalizeBranchForExternalFetch(String branchRef, @Nullable String esUpstreamRemote) {
        if (isShaRef(branchRef)) {
            throw new IllegalArgumentException(
                "Cannot use a commit SHA ("
                    + branchRef
                    + ") as --branch when fetching external changelog sources: "
                    + "git fetch on the remote repository requires a branch or tag name. "
                    + "Local Elasticsearch changelog YAML can still be checked out from a SHA; "
                    + "pass a named branch for --branch (and use --bc-ref for the build candidate when applicable)."
            );
        }
        for (String prefix : KNOWN_REMOTE_PREFIXES) {
            if (branchRef.startsWith(prefix)) {
                return branchRef.substring(prefix.length());
            }
        }
        if (esUpstreamRemote != null && esUpstreamRemote.isBlank() == false) {
            String remotePrefix = esUpstreamRemote + "/";
            if (branchRef.startsWith(remotePrefix)) {
                return branchRef.substring(remotePrefix.length());
            }

View on GitHub (pinned to db6a809a66)

Solutions

1. Pass a real branch name to --branch (e.g. --branch 8.x) and pass the build-candidate SHA via --bc-ref instead.
2. If you only have a SHA and want local Elasticsearch changelog YAML, that path still supports SHAs via --bc-ref; external sources require the named branch.
3. Update release scripts that pass SHAs as --branch to split them into --branch <name> and --bc-ref <sha>.

Example fix

// before
./gradlew bundleChangelogs --branch abc123def456...
// after
./gradlew bundleChangelogs --branch 8.x --bc-ref abc123def456...

static boolean isShaRef(String ref) { return ref.matches("^[0-9a-f]{4,40}$"); }
if (isShaRef(branchArg)) {
    throw new IllegalArgumentException("Pass a named branch via --branch; use --bc-ref for SHAs.");
}

When it happens

Trigger: The user supplies a 40-char (or short) hex SHA as --branch. Because external changelog sources are fetched from their own remotes where a commit SHA is not a fetchable refspec, normalizeBranchForExternalFetch refuses it and throws IllegalArgumentException with remediation guidance.

Common situations: Copy-pasting a build-candidate SHA into --branch instead of --bc-ref; assuming a SHA works universally for local and external checkouts; release tooling that previously accepted SHAs before external sources were added.

Related errors

• 'branch' not specified.
• Changelog directory contains changes that will be wiped out
• Failed to fetch branch {normalizedBranch} from {sourceRepo}
• Output file not specified
• Failed to delete some files: {files}

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