theonedev/onedev · error · NotFoundException

Branch not found: ${branchName}

Error message

Branch not found: ${branchName}

What it means

GET /repositories/{projectId}/branches/{branchName} throws NotFoundException with message 'Branch not found: {branchName}' when project.getBranchRef returns null, i.e. no ref matching that branch exists in the repository.

Source

Thrown at server-core/src/main/java/io/onedev/server/rest/resource/RepositoryResource.java:139

		}

		return Response.ok().build();
	}

	@Api(order=20, description="Get specified branch")
	@Path("/{projectId}/branches/{branch:.*}")
	@GET
	public RefResponse getBranch(
			@PathParam("projectId") Long projectId, 
			@PathParam("branch") @Api(example="test-branch") String branchName) {
		Project project = projectService.load(projectId);
		if (!SecurityUtils.canReadCode(project)) {
			throw new UnauthorizedException();
		}

		RefFacade ref = project.getBranchRef(branchName);
		if (ref == null)
			throw new NotFoundException("Branch not found: " + branchName);

		RefResponse response = new RefResponse();
		
		response.refName = ref.getName();
		response.commitHash = project.getRevCommit(ref.getObjectId(), true).getName();
		
		return response;
	}

	@Api(order=30, description="Create a new branch")
	@Path("/{projectId}/branches")
	@POST
	public Response createBranch(@PathParam("projectId") Long projectId, @NotNull CreateBranchRequest request) {
		Project project = projectService.load(projectId);
		User user = SecurityUtils.getUser();
		if (!SecurityUtils.canWriteCode(project)) 
			throw new UnauthorizedException();
		else if (project.getBranchRef(request.getBranchName()) != null) 

View on GitHub (pinned to d44925c47c)

Solutions

1. Call GET /{projectId}/branches and pick an exact name from the list
2. Fix spelling/casing of branchName to match an existing branch
3. Create/push the branch before querying it

List<String> branches = GET("/repositories/" + projectId + "/branches");
if (!branches.contains(branchName))
    throw new IllegalArgumentException("Branch does not exist: " + branchName);

try {
    ref = client.getBranch(projectId, branchName);
} catch (NotFoundException e) {
    // fall back to default branch or refresh branch list
}

When it happens

Trigger: Querying a branch name that was deleted; typo in the branch name; using full ref name (refs/heads/main) where short name is expected; querying before the branch was pushed.

Common situations: CI referencing renamed branches; stale caches of branch lists after branch deletion; case-sensitivity mismatches (git refs are case-sensitive on Linux).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Tag not found: ${tagName}
• User not found: ${userName}
• Issue not found: ${referenceString}
• Not found
• Unable to find commit to import build spec (import project:

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/37eb3b8260cc061d. Report an issue: GitHub.