Introduction

RefNotFoundException: Ref master cannot be resolved means JGit was asked to use a branch reference that does not exist in the repository state it can currently see. The most common reason today is simple: many repositories use main, not master.

What the Error Actually Means

In Git, a ref is a named pointer such as a branch, tag, or HEAD. When JGit tries to check out, resolve, or inspect master, it expects to find a reference like refs/heads/master or a corresponding remote-tracking ref.

If that ref is missing, JGit throws:

org.eclipse.jgit.api.errors.RefNotFoundException: Ref master cannot be resolved

That message does not automatically mean the repository is broken. It often means the code made an outdated assumption about the branch name.

The Most Common Causes

The Repository Uses main

A large number of repositories renamed their default branch from master to main. Hardcoded checkout code is the first thing to inspect.

git.checkout().setName("master").call();

If the repository only has main, that line will fail.

The Repository Is Empty

A newly initialized repository without a first commit has no meaningful branch tip to resolve. In that case, even a correct branch name may fail because there is no commit yet.

The Clone Fetched a Different Branch Set

If your code uses a shallow clone, a restricted refspec, or a custom fetch configuration, the branch you expect may not be present locally.

You Meant Remote Tracking, Not Local

Sometimes the branch exists remotely as origin/main, but your code tries to resolve a nonexistent local master.

How to Inspect Available Branches in JGit

Instead of guessing, list the refs that are actually available:

1import java.io.File;
2import org.eclipse.jgit.api.Git;
3import org.eclipse.jgit.lib.Ref;
4
5public class ListBranches {
6    public static void main(String[] args) throws Exception {
7        try (Git git = Git.open(new File("."))) {
8            for (Ref ref : git.branchList().call()) {
9                System.out.println(ref.getName());
10            }
11        }
12    }
13}

Typical output looks like:

refs/heads/main
refs/heads/release

That immediately tells you whether master exists.

Fixing the Checkout Logic

If the repository uses main, update the code accordingly:

git.checkout().setName("main").call();

If you need to create a local branch from a remote-tracking branch:

1git.checkout()
2    .setCreateBranch(true)
3    .setName("main")
4    .setStartPoint("origin/main")
5    .call();

That is a common fix after cloning.

Avoid Hardcoding the Wrong Default

A more robust approach is to inspect the repository first and choose a branch that actually exists. This example prefers main, then master:

1import java.io.File;
2import java.util.List;
3import java.util.stream.Collectors;
4import org.eclipse.jgit.api.Git;
5
6public class SmartCheckout {
7    public static void main(String[] args) throws Exception {
8        try (Git git = Git.open(new File("."))) {
9            List<String> branches = git.branchList().call().stream()
10                .map(ref -> ref.getName())
11                .collect(Collectors.toList());
12
13            String target =
14                branches.contains("refs/heads/main") ? "main" :
15                branches.contains("refs/heads/master") ? "master" :
16                null;
17
18            if (target == null) {
19                throw new IllegalStateException("No main or master branch found");
20            }
21
22            git.checkout().setName(target).call();
23        }
24    }
25}

This removes the hidden assumption that every repository still looks the same.

Empty Repository Edge Case

If the repository has no commits yet, branch resolution will still fail because there is nothing to point to. In that case, create the initial commit first with normal Git workflow, then retry the JGit operation.

For debugging, it is worth checking whether HEAD resolves at all. If it does not, you may be dealing with an unborn branch rather than a renamed branch.

Common Pitfalls

The biggest mistake is treating master as a universal default forever. That assumption is no longer safe.

Another common issue is mixing up local and remote refs. main, refs/heads/main, and origin/main are related but not interchangeable in every API call. Read the specific JGit method contract before passing a ref name.

It is also easy to misread an empty repository as a missing-branch problem. If there are no commits, no branch tip can be resolved usefully.

Summary

• 'Ref master cannot be resolved usually means the requested branch ref does not exist locally.'
• The most common modern cause is that the repository uses main instead of master.
• List branches with JGit before hardcoding checkout logic.
• Distinguish local branch names from remote-tracking refs such as origin/main.
• If the repository has no commits yet, branch resolution may fail even with the expected name.