theonedev/onedev · error · ExplicitException

No workspace context found for specified token

Error message

No workspace context found for specified token

What it means

Thrown by the internal context-lookup helper (used e.g. by getWorkspaceContext(token, mustExist)) when no server in the cluster holds a WorkspaceContext under the given access token and mustExist is true. Tokens identify active workspace contexts distributed across servers; an unknown token means no workspace is associated with it.

Source

Thrown at server-core/src/main/java/io/onedev/server/workspace/DefaultWorkspaceService.java:1088

				return null;
			}

		});
	}

	private String getTerminalKey(Long workspaceId, String shellId) {
		return workspaceId + ":" + shellId;
	}

	@Override
	public WorkspaceContext getWorkspaceContext(String token, boolean mustExist) {
		var contextMap = clusterService.runOnAllServers(() -> workspaceContexts.get(token));
		var context = contextMap.values().stream()
				.filter(Objects::nonNull)
				.findFirst()
				.orElse(null);
		if (mustExist && context == null)
			throw new ExplicitException("No workspace context found for specified token");
		return context;
	}

	@Sessional
	@Override
	public GitExecutionResult executeGitCommand(Workspace workspace, String[] gitArgs) {		
		var workspaceId = workspace.getId();
		var server = workspaceServers.get(workspaceId);
		if (server == null)
			throw new ExplicitException("Workspace server not found");

		return clusterService.runOnServer(server, () -> {
			var runtime = workspaceRuntimes.get(workspaceId);
			if (runtime != null) {
				return runtime.executeGitCommand(gitArgs);
			} else {
				return new GitExecutionResult(new byte[0], "Workspace is not active".getBytes(UTF_8), 1);
			}

View on GitHub (pinned to d44925c47c)

Solutions

1. Regenerate the workspace access token and retry with the fresh value.
2. Confirm the workspace is running and its context was created before using the token.
3. Check the token for typos, truncation, or encoding issues.
4. Restart the workspace if the server was restarted and contexts were lost.

Example fix

// before
var context = workspaceService.getWorkspaceContext(token, true);
// after
if (token == null || token.isBlank())
    throw new ExplicitException("Workspace token is required");
var context = workspaceService.getWorkspaceContext(token, true);

// Java
if (token == null || token.isBlank())
    throw new ExplicitException("A workspace token is required");

try { ctx = workspaceService.getWorkspaceContext(token, true); } catch (ExplicitException e) { token = requestNewToken(); ctx = workspaceService.getWorkspaceContext(token, true); }

When it happens

Trigger: Calling workspaceService.getWorkspaceContext(token, true) (or an API authenticating by that token) where the token is expired, revoked, mistyped, or belongs to a workspace that already terminated.

Common situations: Client automation using a stale workspace token after the workspace stopped; token copied with whitespace/truncation; server restarted and in-memory contexts cleared; connecting from an external tool before the workspace context was established.

Related errors

• Not authenticated
• Unable to import build spec (import project: {0}, import rev
• Invalid access token
• Authentication required
• Invalid access token

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