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

Ref name is required when commit hash is specified

Error message

Ref name is required when commit hash is specified

What it means

OneDev's TodResource (AI tool endpoint) throws this NotAcceptableException when submitting a job/build with a raw commit hash but no ref name. The ref name is required to resolve the commit context (branch/tag bookkeeping) for the build, so passing commitHash without refName is rejected before submission.

Source

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

            throw new UnauthenticatedException();

        var project = getProject(currentProjectPath);

        var jobName = trimToNull((String)data.get("jobName"));
        if (jobName == null)
            throw new NotAcceptableException("Job name is required");

        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) {

View on GitHub (pinned to d44925c47c)

Solutions

1. Add a 'refName' entry to the request data (e.g. the branch or tag the commit belongs to) whenever 'commitHash' is supplied.
2. Alternatively, omit 'commitHash' and specify only 'branch' or 'tag' so the resource derives refName via GitUtils.branch2ref/tag2ref.
3. If you only know the hash, resolve its containing ref yourself before calling and pass that as refName.

Example fix

// before
data.put("commitHash", "a1b2c3d4...");
// after
data.put("commitHash", "a1b2c3d4...");
data.put("refName", "refs/heads/main");

// Java/JS caller-side check
if (data.commitHash != null && !(data.refName ?? "").trim()) {
  throw new Error("refName must be provided together with commitHash");
}

function hasRefName(d) { return typeof d.refName === "string" && d.refName.trim().length > 0; }

try { submit(data); } catch (e) { if (e.status === 406 && /Ref name is required/.test(e.message)) { console.error("Add refName when passing commitHash"); } else throw e; }

When it happens

Trigger: Calling the job-submit tool endpoint with data containing 'commitHash' set but 'refName' null or blank. The branch and tag fields may be set or unset; only commitHash presence triggers the refName check.

Common situations: AI agents or API callers pinning a build to an exact SHA and forgetting to supply the refName field; tools that extract a commit hash from a webhook but drop the branch context.

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

• Either commit hash, branch or tag should be 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/ef52d5701a4a7205. Report an issue: GitHub.