theonedev/onedev · error · IllegalArgumentException

revision parameter has to be specified

Error message

revision parameter has to be specified

What it means

OneDev's ArchiveResource serves project source archives (zip/tar.gz) over a REST-style resource URL. Before generating the archive it parses query parameters and rejects the request with this IllegalArgumentException when the required 'revision' parameter is blank or absent, because an archive cannot be generated without knowing which commit/branch/tag to archive.

Source

Thrown at server-core/src/main/java/io/onedev/server/web/resource/ArchiveResource.java:65

	private static final String PARAM_PROJECT = "project";
	
	private static final String PARAM_REVISION = "revision";
	
	private static final String PARAM_FORMAT = "format";
	
	public static final String FORMAT_ZIP = "zip";
	
	public static final String FORMAT_TGZ = "tgz";
	
	@Override
	protected ResourceResponse newResourceResponse(Attributes attributes) {
		PageParameters params = attributes.getParameters();

		Long projectId = params.get(PARAM_PROJECT).toLong();
		
		String revision = params.get(PARAM_REVISION).toString();
		if (StringUtils.isBlank(revision))
			throw new IllegalArgumentException("revision parameter has to be specified");
		
		String format = params.get(PARAM_FORMAT).toString();
		if (!FORMAT_ZIP.equals(format) && !FORMAT_TGZ.equals(format)) {
			throw new IllegalArgumentException("format parameter should be specified either zip or tar.gz");
		}
		
		if (!SecurityUtils.isSystem()) {
			// Perform database operations only if it is not a cluster access to avoid possible deadlocks
			Project project = OneDev.getInstance(ProjectService.class).load(projectId);
			if (!SecurityUtils.canReadCode(project)) 
				throw new UnauthorizedException();
		}
		
		ResourceResponse response = new ResourceResponse();
		response.setContentType(MimeTypes.OCTET_STREAM);
		
		response.disableCaching();
		

View on GitHub (pinned to d44925c47c)

Solutions

1. Add the revision query parameter to the archive URL, e.g. ?project=<id>&revision=<commit-sha-or-branch>&format=zip
2. If the revision comes from a variable, verify it is non-empty before constructing the URL (echo/check in the script or CI job)
3. Use OneDev's UI 'Download archive' action to obtain a correctly formed URL and compare with yours

Example fix

// before
GET /~resources/archive?project=1&format=zip
// after
GET /~resources/archive?project=1&revision=abc1234&format=zip

if (!revision) throw new Error('archive URL requires a non-empty revision (commit SHA, branch, or tag)');
const url = `~/.archive?project=${projectId}&revision=${encodeURIComponent(revision)}&format=zip`;

try { await fetch(url); } catch (e) { console.error('Archive request failed - check revision/format params and permissions:', e); }

When it happens

Trigger: Hitting the archive resource URL (~/.archive or project archive endpoint) with only the 'project' (and optionally 'format') parameters while omitting or leaving empty the 'revision' query parameter.

Common situations: Hand-built URLs in scripts or CI steps that forgot revision; a templated URL where the revision variable interpolated to empty (e.g. unset CI variable for branch/commit SHA); URL encoding stripping the parameter.

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

• format parameter should be specified either zip or tar.gz
• Artifact path has to be specified
• Parameter 'attachment-group' has to be specified
• Revision and path should be specified
• Unauthenticated

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