theonedev/onedev · error · ExplicitException

Generated branch name is only available when issue state…

Error message

Generated branch name is only available when issue state triggers are used

What it means

GeneratedBranchName is a branch name provider that asks IssueService.suggestBranch to derive a branch name from the build's linked issue. Branch suggestions only exist for builds triggered by issue state transitions, so when build.getIssue() is null this ExplicitException is thrown.

Solutions

Only use GeneratedBranchName for jobs triggered by issue state activation (build.getIssue() != null).
For push/cron builds, use a fixed branch name or a different branch name provider.
Ensure contributors create commits on branches matching the issue's suggested branch pattern so the issue is linked to the build.
Add a condition to the job so it only runs for issue-triggered builds.

Example fix

// before (runs on push too)
branchName: !<GeneratedBranchName>
// after: guard the job with an issue state trigger, or use a literal
branchName: feature/manual-build

Defensive patterns

Strategy: try-catch

Validate before calling

// Only configure GeneratedBranchName under an issue state trigger
if (build.getIssue() == null) {
    branchName = "manual-" + build.getCommitId().substring(0, 8); // fallback for non-issue builds
} else {
    branchName = OneDev.getInstance(IssueService.class).suggestBranch(build.getIssue());
}

Try / catch

// catch ExplicitException and fall back
try {
    branchName = generatedBranchName.getBranchName(build);
} catch (ExplicitException e) {
    branchName = "fallback-branch";
}

Prevention

Use GeneratedBranchName only with issue state activation triggers.
Add job conditions restricting the job to issue-triggered builds.
Educate contributors to use the suggested branch name so builds link to issues.

When it happens

Trigger: Using branchName: !<GeneratedBranchName> on a build that has no associated issue — i.e. triggered by commit push, cron, or manual dispatch instead of an issue state trigger (IssueStateActivation).

Common situations: Reusing a CI job definition that works for issue-fix builds on regular push builds; configuring the branch name provider on a job scheduled by cron; issue linkage lost because the commit was not made with the suggested branch name pattern.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at server-core/src/main/java/io/onedev/server/buildspec/step/branchnameprovider/GeneratedBranchName.java:21

import io.onedev.commons.utils.ExplicitException;
import io.onedev.server.OneDev;
import io.onedev.server.annotation.Editable;
import io.onedev.server.model.Build;
import io.onedev.server.service.IssueService;

@Editable(order=100, name="Use generated branch name", description="""
        Generate branch name based on issue title. It is highly recommended to configure 
		AI model in <i>Administration / AI Settings</i> to generate good branch name""")
public class GeneratedBranchName implements BranchNameProvider {

	private static final long serialVersionUID = 1L;

	@Override
	public String getBranchName(Build build) {
		if (build.getIssue() != null) {
			return OneDev.getInstance(IssueService.class).suggestBranch(build.getIssue());
		} else {
			throw new ExplicitException("Generated branch name is only available when issue state triggers are used");
		}
	}

}

View on GitHub (pinned to d44925c47c)