{"record":{"id":"c8f4e3a289a8daff","repo":"theonedev/onedev","slug":"workspace-runtime-not-found","errorCode":null,"errorMessage":"Workspace runtime not found","messagePattern":"Workspace runtime not found","errorType":"exception","errorClass":"ExplicitException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/workspace/DefaultWorkspaceService.java","lineNumber":861,"sourceCode":"\t\tvar logDir = projectService.getSubDir(projectId, WORKSPACE_LOGS_DIR);\n\t\treturn new File(logDir, workspaceNumber.toString());\n\t}\n\n\t@Sessional\n\t@Override\n\tpublic String openShell(Workspace workspace, String label, @Nullable String command,\n\t\t\t\t\t\t\t @Nullable ShellOutputCallback outputCallback) {\n\t\tvar workspaceId = workspace.getId();\n\t\tvar server = workspaceServers.get(workspaceId);\n\t\tif (server == null)\n\t\t\tthrow new ExplicitException(\"Workspace server not found\");\n\t\tvar shellId = clusterService.runOnServer(server, new ClusterTask<String>() {\n\n\t\t\t@Override\n\t\t\tpublic String call() throws Exception {\n\t\t\t\tvar runtime = workspaceRuntimes.get(workspaceId);\n\t\t\t\tif (runtime == null)\n\t\t\t\t\tthrow new ExplicitException(\"Workspace runtime not found\");\n\t\t\t\tvar shellIdRef = new AtomicReference<String>(null);\n\t\t\t\tvar shellReady = new CompletableFuture<String>();\n\t\t\t\tvar firstOutputSeen = new AtomicBoolean(false);\n\t\t\t\tshellIdRef.set(runtime.openShell(new Terminal() {\n\n\t\t\t\t\t@Override\n\t\t\t\t\tpublic void onShellOutput(String base64Data) {\n\t\t\t\t\t\tvar shellId = shellIdRef.get();\n\t\t\t\t\t\tif (shellId != null) {\n\t\t\t\t\t\t\t// Use runOnAllServers instead of submitToAllServers to preserve output order\n\t\t\t\t\t\t\tclusterService.runOnAllServers(newHandleShellOutputTask(workspaceId, shellId, base64Data));\n\t\t\t\t\t\t}\n\t\t\t\t\t\tif (outputCallback != null) {\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\toutputCallback.onOutput(base64Data);\n\t\t\t\t\t\t\t} catch (Throwable e) {\n\t\t\t\t\t\t\t\tlogger.error(\"Error calling shell output callback\", e);\n\t\t\t\t\t\t\t}","sourceCodeStart":843,"sourceCodeEnd":879,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/workspace/DefaultWorkspaceService.java#L843-L879","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry after confirming the workspace is actually running (check workspace status).","Restart/recreate the workspace to restore its runtime.","Check the hosting node's container runtime (docker) health and restart it if needed.","Investigate cluster/node events for recent restarts that wiped in-memory runtimes."],"exampleFix":"// before\nshellId = runtime.openShell(terminal);\n// after\nWorkspaceRuntime runtime = workspaceRuntimes.get(workspaceId);\nif (runtime == null)\n    throw new ExplicitException(\"Workspace is not running; cannot open shell\");","handlingStrategy":"retry","validationCode":"// Java\nif (workspace.getStatus() != WorkspaceStatus.RUNNING)\n    throw new ExplicitException(\"Workspace not running; runtime unavailable\");","typeGuard":null,"tryCatchPattern":"try { workspaceService.openShell(workspace, label, null, cb); } catch (ExplicitException e) { Thread.sleep(2000); workspaceService.openShell(workspace, label, null, cb); }","preventionTips":["Retry transient runtime lookups with short backoff","Monitor container runtime (docker) health on cluster nodes","Avoid shell access during workspace stop/provision transitions"],"tags":["onedev","workspace","runtime","cluster"],"backgroundTag":"resource-not-found","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}