theonedev/onedev · error · ExplicitException

Branch creation prohibited by branch protection rule

Error message

Branch creation prohibited by branch protection rule

What it means

POST /{projectId}/branches throws ExplicitException when a branch protection rule for the requested branch name has 'prevent creation' enabled. This is an intentional policy rejection by OneDev, not a system failure.

Source

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

		
		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
	public Response deleteBranch(@PathParam("projectId") Long projectId, 
			@PathParam("branch") @Api(example="test-branch") String branchName) {

View on GitHub (pinned to d44925c47c)

Solutions

1. Ask a project admin to allow creation for that pattern in Branch Protection settings
2. Create a branch with a name not matched by the protection rule
3. Use an allowed alternative (e.g. create branch then push, only if policy permits)

Example fix

// before
POST /~api/1/branches {"branchName":"release/1.0","revision":"main"} // blocked
// after (name outside protected pattern)
POST /~api/1/branches {"branchName":"feature/release-1.0-prep","revision":"main"}

// review branch protection rules via project settings/API before naming branches
const forbidden = protectionRules.some(r => r.preventCreation && matches(r.pattern, name));
if (forbidden) throw new Error('branch name protected');

try {
  createBranch(projectId, req);
} catch (ExplicitException e) {
  // show policy message to user; suggest compliant name
}

When it happens

Trigger: Calling POST /~api/{projectId}/branches where the branch name matches a branch protection pattern whose 'prevent creation' option is checked, for the acting user.

Common situations: Creating branches matching protected patterns like 'release/*' or 'main' that admins locked; automated tooling unaware of protection rules; permission model changes after new protection rules were added.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• Cannot create this branch as branch protection setting requi
• Unable to remove mandatory reviewers:
• 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/e537597d22fad016. Report an issue: GitHub.