theonedev/onedev · error · NotAcceptableException

Branch '${request.getBranchName()}' already exists

Error message

Branch '${request.getBranchName()}' already exists

What it means

POST /{projectId}/branches throws NotAcceptableException when the requested branch name already exists as a ref in the repository. OneDev checks project.getBranchRef(branchName) before creating and refuses duplicate branch creation.

Source

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

		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) 
			throw new NotAcceptableException("Branch '" + request.getBranchName() + "' already exists");
		else if (project.getBranchProtection(request.getBranchName(), user).isPreventCreation()) 
			throw new ExplicitException("Branch creation prohibited by branch protection rule");
		
		if (!project.isCommitSignatureRequirementSatisfied(
				user, request.getBranchName(), 
				project.getRevCommit(request.getRevision(), true))) {
			throw new ExplicitException("Cannot create this branch as branch protection setting "
					+ "requires valid signature on head commit");
		}
		
		gitService.createBranch(project, request.getBranchName(), request.getRevision());

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

	@Api(order=40, description="Delete specified branch")
	@Path("/{projectId}/branches/{branch:.*}")
	@DELETE

View on GitHub (pinned to d44925c47c)

Solutions

1. Choose a different, unique branch name
2. Delete or rename the existing branch first if it is obsolete
3. Check GET /~api/{projectId}/branches (or branch existence) before POST and skip creation if present
4. Use a timestamped or run-id suffixed branch name in automation

Example fix

// before
POST /~api/1/branches {"branchName":"release","revision":"main"}
// after
POST /~api/1/branches {"branchName":"release-2026-09-06","revision":"main"}

const exists = (await api.get(`/projects/${id}/branches`)).data.includes(name);
if (exists) throw new Error(`Branch ${name} already exists`);

try {
  createBranch(projectId, req);
} catch (NotAcceptableException e) {
  // treat as idempotent success or pick a new branch name
}

When it happens

Trigger: Calling POST /~api/{projectId}/branches with a branchName that resolves to an existing git ref (e.g. 'refs/heads/main').

Common situations: Rerunning an idempotency-unguarded CI script that creates a branch; branch created concurrently by another user or automation; case-sensitivity confusion with existing branch names.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• Tag '${request.getTagName()}' already exists
• Branch not exist:
• Ref name should start with refs/
• Specified commit is not reachable from specified ref
• Branch not found: ${branchName}

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