theonedev/onedev · error · ExplicitException

Workspace runtime not found

Error message

Workspace runtime not found

What it means

Thrown inside the ClusterTask dispatched by openShell(): the request reached the correct workspace server, but workspaceRuntimes contains no runtime for the workspace id. The server knows about the workspace but the actual container/runtime handle is gone, so no shell can be opened. Typically a race or stale-state condition between server registration and runtime lifecycle.

Source

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

		var logDir = projectService.getSubDir(projectId, WORKSPACE_LOGS_DIR);
		return new File(logDir, workspaceNumber.toString());
	}

	@Sessional
	@Override
	public String openShell(Workspace workspace, String label, @Nullable String command,
							 @Nullable ShellOutputCallback outputCallback) {
		var workspaceId = workspace.getId();
		var server = workspaceServers.get(workspaceId);
		if (server == null)
			throw new ExplicitException("Workspace server not found");
		var shellId = clusterService.runOnServer(server, new ClusterTask<String>() {

			@Override
			public String call() throws Exception {
				var runtime = workspaceRuntimes.get(workspaceId);
				if (runtime == null)
					throw new ExplicitException("Workspace runtime not found");
				var shellIdRef = new AtomicReference<String>(null);
				var shellReady = new CompletableFuture<String>();
				var firstOutputSeen = new AtomicBoolean(false);
				shellIdRef.set(runtime.openShell(new Terminal() {

					@Override
					public void onShellOutput(String base64Data) {
						var shellId = shellIdRef.get();
						if (shellId != null) {
							// Use runOnAllServers instead of submitToAllServers to preserve output order
							clusterService.runOnAllServers(newHandleShellOutputTask(workspaceId, shellId, base64Data));
						}
						if (outputCallback != null) {
							try {
								outputCallback.onOutput(base64Data);
							} catch (Throwable e) {
								logger.error("Error calling shell output callback", e);
							}

View on GitHub (pinned to d44925c47c)

Solutions

1. Retry after confirming the workspace is actually running (check workspace status).
2. Restart/recreate the workspace to restore its runtime.
3. Check the hosting node's container runtime (docker) health and restart it if needed.
4. Investigate cluster/node events for recent restarts that wiped in-memory runtimes.

Example fix

// before
shellId = runtime.openShell(terminal);
// after
WorkspaceRuntime runtime = workspaceRuntimes.get(workspaceId);
if (runtime == null)
    throw new ExplicitException("Workspace is not running; cannot open shell");

// Java
if (workspace.getStatus() != WorkspaceStatus.RUNNING)
    throw new ExplicitException("Workspace not running; runtime unavailable");

try { workspaceService.openShell(workspace, label, null, cb); } catch (ExplicitException e) { Thread.sleep(2000); workspaceService.openShell(workspace, label, null, cb); }

When it happens

Trigger: openShell routes to the owning server, but the runtime was torn down (workspace stopping/stopped, container crashed, node restart cleared in-memory runtimes) between server lookup and runtime lookup.

Common situations: Opening a shell just as the workspace is terminating; Docker/containerd restarted and runtime records were lost; cluster node rebooted without graceful workspace shutdown; UI race where workspace status looks running but runtime already died.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Workspace server not found
• Project not found:
• Invalid access token
• Cannot find server managing allocated agent, please retry la
• This workspace is provisioned on server previously, and cann

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