What causes "Unable to find agent {0}" in theonedev/onedev?

Check the agent name in Admin > Agents and use the exact name in the URL.

theonedev/onedev · error · ExplicitException

Unable to find agent {0}

Error message

Unable to find agent {0}

What it means

AgentDetailPage constructor resolves the 'agent' page parameter to an Agent by name and throws this ExplicitException (MessageFormat with the name) when no such agent exists, so the admin page fails fast instead of rendering with a null model.

Source

Thrown at server-core/src/main/java/io/onedev/server/web/page/admin/buildsetting/agent/AgentDetailPage.java:41

import io.onedev.server.web.component.tabbable.Tab;
import io.onedev.server.web.component.tabbable.Tabbable;
import io.onedev.server.web.page.admin.AdministrationPage;

public abstract class AgentDetailPage extends AdministrationPage {

	public static final String PARAM_AGENT = "agent";
	
	protected final IModel<Agent> agentModel;
	
	public AgentDetailPage(PageParameters params) {
		super(params);

		String agentName = params.get(PARAM_AGENT).toString();
		
		Agent agent = OneDev.getInstance(AgentService.class).findByName(agentName);
		
		if (agent == null) 
			throw new ExplicitException(MessageFormat.format(_T("Unable to find agent {0}"), agentName));
		
		Long agentId = agent.getId();
		
		agentModel = new LoadableDetachableModel<Agent>() {

			@Override
			protected Agent load() {
				return OneDev.getInstance(AgentService.class).load(agentId);
			}
			
		};
		
		// we do not need to reload the project this time as we already have that object on hand
		agentModel.setObject(agent);
	}
	
	@Override
	protected void onInitialize() {

View on GitHub (pinned to d44925c47c)

Solutions

Check the agent name in Admin > Agents and use the exact name in the URL.
Update or remove stale bookmarks/links pointing at the removed agent.
Re-register the agent if it was deleted by mistake.

Example fix

// before: /~admin/agents/build-agent-1 (agent renamed)
// after: /~admin/agents/runner-1 (current agent name)

Defensive patterns

Strategy: fallback

Validate before calling

var agent = OneDev.getInstance(AgentService.class).findByName(name);
if (agent == null) { /* redirect to agent list instead of deep link */ }

Try / catch

try {
    return AgentDetailPage.forAgent(name);
} catch (ExplicitException e) {
    return redirectToAgentList();
}

Prevention

List agents from the Admin page rather than bookmarks.
Refresh links after renaming/removing agents.
Validate agent names against AgentService before building links.

When it happens

Trigger: Opening /~admin/agents/<name> (or a link/bookmark) where <name> does not match any registered build agent.

Common situations: Agent was deleted or renamed after a bookmark/link was saved; typo in agent name; agent registered on a different OneDev instance (restored DB or changed server).

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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