theonedev/onedev · error · UnauthorizedException

Unauthorized

Error message

Unauthorized

What it means

AgentResource serves the OneDev agent installation package, restricted to administrators. After the administrator check passes, it verifies that the packaged agent directory exists under Bootstrap.installDir; if it does not, it throws this ExplicitException because the server installation has no agent package to distribute.

Source

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

import io.onedev.commons.utils.FileUtils;
import io.onedev.commons.utils.StringUtils;
import io.onedev.commons.utils.TarUtils;
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 {

View on GitHub (pinned to d44925c47c)

Solutions

1. Restore the agent package directory under the OneDev install dir (reinstall/repair OneDev or copy the bundled 'agent' folder from a complete distribution).
2. Verify Bootstrap.installDir points to the real installation root (fix launch script/env if wrong).
3. Upgrade OneDev to a distribution that bundles the agent package.
4. If in a container, use the official image/complete archive rather than a trimmed build.

Example fix

// before: site dir missing package
ls /opt/onedev  # no 'agent' dir

// after: restore from distribution
cp -r onedev-complete/agent /opt/onedev/agent

// Check the package exists on the server before requesting download
File agentDir = new File(Bootstrap.installDir, "agent");
if (!agentDir.exists())
    throw new IllegalStateException("Agent package missing; reinstall OneDev distribution");

When it happens

Trigger: Administrator requests the agent package download while the '<installDir>/agent' directory is missing on the server host.

Common situations: Partial or custom server installation that omitted the bundled agent files; installDir misconfigured (wrong path or relative path in a container); upgrade/cleanup script deleted the agent directory; running the server from a stripped-down distribution.

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.

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• No agent package to download
• 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/c177e088ea939e07. Report an issue: GitHub.