What causes "build number has to be specified" in theonedev/onedev?

Add the build number parameter, e.g. /~resource/buildlogs?project=1&build=42.

theonedev/onedev · error · IllegalArgumentException

build number has to be specified

Error message

build number has to be specified

What it means

BuildLogResource serves build log files for /~resource/buildlogs/... URLs. The 'build' parameter (PARAM_BUILD) must carry the build number; when toOptionalLong() yields null the resource throws IllegalArgumentException("build number has to be specified").

Source

Thrown at server-core/src/main/java/io/onedev/server/web/resource/BuildLogResource.java:53

import io.onedev.server.service.ProjectService;
import io.onedev.server.util.IOUtils;

public class BuildLogResource extends AbstractResource {

	private static final long serialVersionUID = 1L;

	private static final String PARAM_PROJECT = "project";
	
	private static final String PARAM_BUILD = "build";
	
	@Override
	protected ResourceResponse newResourceResponse(Attributes attributes) {
		PageParameters params = attributes.getParameters();

		Long projectId = params.get(PARAM_PROJECT).toLong();
		Long buildNumber = params.get(PARAM_BUILD).toOptionalLong();
		if (buildNumber == null)
			throw new IllegalArgumentException("build number has to be specified");

		if (!SecurityUtils.isSystem()) {
			Project project = getProjectService().load(projectId);			
			Build build = getBuildService().find(project, buildNumber);

			if (build == null) {
				String message = String.format("Unable to find build (project: %s, build number: %d)", 
						project.getPath(), buildNumber);
				throw new EntityNotFoundException(message);
			}
			
			if (!SecurityUtils.canAccessLog(build))
				throw new UnauthorizedException();
		}
		
		ResourceResponse response = new ResourceResponse();
		response.setContentType(MimeTypes.OCTET_STREAM);

View on GitHub (pinned to d44925c47c)

Solutions

Add the build number parameter, e.g. /~resource/buildlogs?project=1&build=42.
Ensure the variable feeding the URL (e.g. $BUILD_NUMBER in pipeline scripts) is actually set and numeric.
Confirm the parameter name matches PARAM_BUILD for your OneDev version.

Example fix

// before
GET /~resource/buildlogs?project=1          -> 400
// after
GET /~resource/buildlogs?project=1&build=42

Defensive patterns

Strategy: validation

Validate before calling

if (!Number.isInteger(Number(buildNumber)) || buildNumber === null || buildNumber === '') {
  throw new Error('build number parameter is required and must be numeric');
}

Type guard

function hasBuildNumber(params) {
  const n = Number(params.build);
  return Number.isInteger(n) && n > 0;
}

Try / catch

try { const log = await fetchLog(projectId, buildNumber); } catch (e) { if (String(e.message).includes('build number has to be specified')) failFast('BUILD_NUMBER env var is not set'); else throw e; }

Prevention

Assert CI variables like BUILD_NUMBER are non-empty before building URLs
Use OneDev's job APIs to obtain the build number rather than guessing
Keep parameter names consistent with the resource documentation

When it happens

Trigger: Requesting the build log resource URL without the build number parameter, or with a non-numeric/empty value that cannot be parsed as a Long.

Common situations: Manually constructed URLs missing &build=N; scripts interpolating an empty BUILD_NUMBER variable; URL templates copied from other resources with different parameter names.

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

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