theonedev/onedev · error · IllegalArgumentException

format parameter should be specified either zip or tar.gz

Error message

format parameter should be specified either zip or tar.gz

What it means

ArchiveResource validates the 'format' parameter and only accepts "zip" or "tar.gz" (constants FORMAT_ZIP/FORMAT_TGZ). Any other value, including an absent or misspelled format, triggers this IllegalArgumentException because the resource cannot pick an archiving strategy.

Source

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

	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();
		
		try {
			String fileName;
			if (GitUtils.ref2branch(revision) != null)
				fileName = GitUtils.ref2branch(revision);

View on GitHub (pinned to d44925c47c)

Solutions

1. Set format=zip or format=tar.gz exactly in the archive URL
2. If defaulting is desired, add the format explicitly in your script rather than relying on omission
3. Check for typos/encoding issues in the query string (e.g. 'tar%2Egz' still decodes to 'tar.gz' and is fine, but 'tar .gz' is not)

Example fix

// before
GET /~resources/archive?project=1&revision=main&format=gzip
// after
GET /~resources/archive?project=1&revision=main&format=tar.gz

const FORMAT_ZIP='zip', FORMAT_TGZ='tar.gz';
if (format !== FORMAT_ZIP && format !== FORMAT_TGZ) throw new Error(`format must be '${FORMAT_ZIP}' or '${FORMAT_TGZ}', got: ${format}`);

function isArchiveFormat(f) { return f === 'zip' || f === 'tar.gz'; }

When it happens

Trigger: Requesting the archive resource with format=<anything other than zip or tar.gz>, or omitting the format parameter entirely so it is null/blank.

Common situations: Typo like 'gzip', 'tar', or 'tgz' instead of the exact 'tar.gz'; dropping the parameter when hand-crafting the URL; proxies or scripts URL-rewriting that mangle the query string.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• revision parameter has to be specified
• Unauthenticated
• Project not specified
• Project not found or inaccessible: <projectPath>
• Authentication required

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