{"record":{"id":"ef52d5701a4a7205","repo":"theonedev/onedev","slug":"ref-name-is-required-when-commit-hash-is-specified","errorCode":null,"errorMessage":"Ref name is required when commit hash is specified","messagePattern":"Ref name is required when commit hash is specified","errorType":"exception","errorClass":"io.onedev.server.exception.NotAcceptableException","httpStatus":406,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/ai/TodResource.java","lineNumber":1702,"sourceCode":"            throw new UnauthenticatedException();\n\n        var project = getProject(currentProjectPath);\n\n        var jobName = trimToNull((String)data.get(\"jobName\"));\n        if (jobName == null)\n            throw new NotAcceptableException(\"Job name is required\");\n\n        if (!SecurityUtils.canRunJob(subject, project, jobName))\t\t\n            throw new UnauthorizedException();\n\n        String refName;\n        var branch = trimToNull((String)data.get(\"branch\"));\n        var tag = trimToNull((String)data.get(\"tag\"));\n        var commitHash = trimToNull((String)data.get(\"commitHash\"));\n        if (commitHash != null) {\n            refName = trimToNull((String)data.get(\"refName\"));\n            if (refName == null) {\n                throw new NotAcceptableException(\"Ref name is required when commit hash is specified\");\n            }\n        } else if (branch != null) {            \n            refName = GitUtils.branch2ref(branch);\n        } else if (tag != null) {\n            refName = GitUtils.tag2ref(tag);\n        } else {\n            throw new NotAcceptableException(\"Either commit hash, branch or tag should be specified\");\n        }\n        if (commitHash == null)\n            commitHash = project.getRevCommit(refName, true).name();\n            \n        Map<String, List<String>> params;\n        var paramData = data.get(\"params\");\n        if (paramData instanceof List) {\n            params = new HashMap<String, List<String>>();\n            List<String> paramPairs = (List<String>) paramData;\n            if (paramPairs != null) {\n                for (var paramPair: paramPairs) {","sourceCodeStart":1684,"sourceCodeEnd":1720,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/ai/TodResource.java#L1684-L1720","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a 'refName' entry to the request data (e.g. the branch or tag the commit belongs to) whenever 'commitHash' is supplied.","Alternatively, omit 'commitHash' and specify only 'branch' or 'tag' so the resource derives refName via GitUtils.branch2ref/tag2ref.","If you only know the hash, resolve its containing ref yourself before calling and pass that as refName."],"exampleFix":"// before\ndata.put(\"commitHash\", \"a1b2c3d4...\");\n// after\ndata.put(\"commitHash\", \"a1b2c3d4...\");\ndata.put(\"refName\", \"refs/heads/main\");","handlingStrategy":"validation","validationCode":"// Java/JS caller-side check\nif (data.commitHash != null && !(data.refName ?? \"\").trim()) {\n  throw new Error(\"refName must be provided together with commitHash\");\n}","typeGuard":"function hasRefName(d) { return typeof d.refName === \"string\" && d.refName.trim().length > 0; }","tryCatchPattern":"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; }","preventionTips":["Treat commitHash and refName as an inseparable pair in your payload builder","Prefer branch/tag-only submissions so refName is derived automatically","Add a schema/validation step on tool payloads before sending"],"tags":["missing-required-parameter","rest-api","git"],"backgroundTag":"missing-required-argument","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}