theonedev/onedev · error · io.onedev.server.exception.NotAcceptableException

Either commit hash, branch or tag should be specified

Error message

Either commit hash, branch or tag should be specified

What it means

TodResource requires a way to determine which revision to build. If none of commitHash, branch, or tag is present in the submitted data, it throws NotAcceptableException because it cannot resolve a refName or commit for jobService.submit.

Source

Thrown at server-core/src/main/java/io/onedev/server/ai/TodResource.java:1709

        if (!SecurityUtils.canRunJob(subject, project, jobName))		
            throw new UnauthorizedException();

        String refName;
        var branch = trimToNull((String)data.get("branch"));
        var tag = trimToNull((String)data.get("tag"));
        var commitHash = trimToNull((String)data.get("commitHash"));
        if (commitHash != null) {
            refName = trimToNull((String)data.get("refName"));
            if (refName == null) {
                throw new NotAcceptableException("Ref name is required when commit hash is specified");
            }
        } else if (branch != null) {            
            refName = GitUtils.branch2ref(branch);
        } else if (tag != null) {
            refName = GitUtils.tag2ref(tag);
        } else {
            throw new NotAcceptableException("Either commit hash, branch or tag should be specified");
        }
        if (commitHash == null)
            commitHash = project.getRevCommit(refName, true).name();
            
        Map<String, List<String>> params;
        var paramData = data.get("params");
        if (paramData instanceof List) {
            params = new HashMap<String, List<String>>();
            List<String> paramPairs = (List<String>) paramData;
            if (paramPairs != null) {
                for (var paramPair: paramPairs) {
                    var paramName = trimToNull(StringUtils.substringBefore(paramPair, "="));
                    var paramValue = trimToNull(StringUtils.substringAfter(paramPair, "="));
                    if (paramName != null && paramValue != null)
                        params.computeIfAbsent(paramName, k -> new ArrayList<>()).add(paramValue);
                }
            }
        } else if (paramData instanceof Map) {

View on GitHub (pinned to d44925c47c)

Solutions

1. Include at least one of 'branch', 'tag', or 'commitHash' (with 'refName') in the request data.
2. For typical CI runs pass the branch: data.put("branch", "main").
3. Check your tool-call payload generation to ensure revision fields are not stripped or trimmed to null.

Example fix

// before
var data = new HashMap<String, Serializable>();
data.put("jobName", "ci");
// after
var data = new HashMap<String, Serializable>();
data.put("jobName", "ci");
data.put("branch", "main");

const revisionFields = [data.commitHash, data.branch, data.tag].filter(v => v && String(v).trim());
if (revisionFields.length === 0) throw new Error("One of commitHash, branch or tag is required");

function hasRevision(d) { return ["commitHash","branch","tag"].some(k => typeof d[k] === "string" && d[k].trim().length > 0); }

try { submit(data); } catch (e) { if (e.status === 406 && /branch or tag should be specified/.test(e.message)) { data.branch = defaultBranch; return submit(data); } throw e; }

When it happens

Trigger: Calling the job-submit tool endpoint where data.get("commitHash"), data.get("branch"), and data.get("tag") are all null/blank.

Common situations: AI agents constructing the submit payload from scratch and omitting all revision fields; callers assuming a default branch is used automatically (OneDev has no such default here).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Ref name is required when commit hash is specified
• Reason is required
• Commit not found
• Specified path is not a directory: ${blobIdent.path}
• Specified path is not a file: ${blobIdent.path}

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