theonedev/onedev · error · ExplicitException

No agent package to download

Error message

No agent package to download

What it means

Identical to the agent-package check in AgentResource: when an administrator requests the agent package but the '<installDir>/agent' directory does not exist on the server, OneDev throws this ExplicitException instead of serving the binary.

Source

Thrown at server-core/src/main/java/io/onedev/server/web/resource/AgentResource.java:43

import io.onedev.commons.utils.ZipUtils;
import io.onedev.server.OneDev;
import io.onedev.server.service.AgentService;
import io.onedev.server.service.AgentTokenService;
import io.onedev.server.service.SettingService;
import io.onedev.server.model.AgentToken;
import io.onedev.server.security.SecurityUtils;

public class AgentResource extends AbstractResource {

	private static final long serialVersionUID = 1L;

	@Override
	protected ResourceResponse newResourceResponse(Attributes attributes) {
		if (!SecurityUtils.isAdministrator()) 
			throw new UnauthorizedException();
		
		if (!new File(Bootstrap.installDir, "agent").exists())
			throw new ExplicitException("No agent package to download");

		ResourceResponse response = new ResourceResponse();
		response.setContentType(MimeTypes.OCTET_STREAM);
		response.disableCaching();
		
		String fileName = StringUtils.substringAfterLast(
				attributes.getRequest().getUrl().getPath(), "/");
		response.setFileName(fileName);
		
		response.setWriteCallback(new WriteCallback() {

			@Override
			public void writeData(Attributes attributes) throws IOException {
				File tempDir = FileUtils.createTempDir("agent");
				try {
					String agentVersion = OneDev.getInstance(AgentService.class).getAgentVersion();
					
					File agentDir = new File(tempDir, "agent");

View on GitHub (pinned to d44925c47c)

Solutions

1. Ensure the complete OneDev distribution's 'agent' directory exists at the install dir; reinstall/repair if missing.
2. Correct Bootstrap.installDir / launch configuration so it points to the directory that actually contains the 'agent' folder.
3. Check disk/cleanup policies that might have deleted the folder and re-extract it from the distribution archive.

Example fix

// before
export ONODEV_INSTALL=/opt/onedev-wrong

// after: point to dir containing 'agent'
export ONODEV_INSTALL=/opt/onedev

// Verify presence of the agent package before download attempts
if (!new File(Bootstrap.installDir, "agent").exists()) {
    // restore from distribution archive first
    throw new IllegalStateException("Missing agent package at " + Bootstrap.installDir);
}

When it happens

Trigger: GET on the agent download resource by an administrator while new File(Bootstrap.installDir, "agent") does not exist.

Common situations: Server installed from a minimal archive without the agent bundle; installDir env/launch config pointing to the wrong directory (e.g. after moving the installation); filesystem cleanup removed the agent folder; running dev build from source without packaged agent resources.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Unauthorized
• Allocated agent not connected to current server, please retr
• Build spec not defined (project: %s, commit: %s)
• Not authorized
• Unable to update attributes as agent is offline

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