{"record":{"id":"0843e28d944ccd7a","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-initialize-shell-session-0843e2","errorCode":null,"errorMessage":"Failed to initialize shell session","messagePattern":"Failed to initialize shell session","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/ShellSessionManager.java","lineNumber":145,"sourceCode":"\t\t\t// Register in global registry for HITL recovery\n\t\t\tfinal Path finalWorkspace = workspace;\n\t\t\tconfig.threadId().ifPresent(threadId -> {\n\t\t\t\tSESSION_REGISTRY.put(threadId, new SessionEntry(session, finalWorkspace));\n\t\t\t\tlog.debug(\"Registered shell session in global registry with threadId: {}\", threadId);\n\t\t\t});\n\n\t\t\tlog.info(\"Started shell session in workspace: {}\", workspace);\n\n\t\t\t// Run startup commands\n\t\t\tfor (String command : startupCommands) {\n\t\t\t\tCommandResult result = session.execute(command, startupTimeout, maxOutputLines, maxOutputBytes);\n\t\t\t\tif (result.isTimedOut() || (result.getExitCode() != null && result.getExitCode() != 0)) {\n\t\t\t\t\tthrow new RuntimeException(\"Startup command failed: \" + command + \", exit code: \" + result.getExitCode());\n\t\t\t\t}\n\t\t\t}\n\t\t} catch (Exception e) {\n\t\t\tcleanup(config);\n\t\t\tthrow new RuntimeException(\"Failed to initialize shell session\", e);\n\t\t}\n\t}\n\n\t/**\n\t * Clean up shell session.\n\t * This removes the session from both the context and the global registry.\n\t */\n\tpublic void cleanup(RunnableConfig config) {\n\t\ttry {\n\t\t\t// Try to get session from context first, then from registry\n\t\t\tShellSession session = (ShellSession) config.context().get(SESSION_INSTANCE_CONTEXT_KEY);\n\t\t\tif (session == null) {\n\t\t\t\tsession = getSessionFromRegistry(config);\n\t\t\t}\n\t\t\tif (session != null) {\n\t\t\t\t// Run shutdown commands\n\t\t\t\tfor (String command : shutdownCommands) {\n\t\t\t\t\ttry {","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/ShellSessionManager.java#L127-L163","documentation":"This is the outer wrapper exception from ShellSessionManager.initialize(): any Exception thrown while creating the shell session (starting the OS process, running startup commands, etc.) is caught, the partial session is cleaned up via cleanup(config), and this RuntimeException is rethrown with the original cause attached. It means shell session creation failed overall, not necessarily because of a startup command exit code.","triggerScenarios":"initialize() throws for any reason: the underlying shell process cannot be started (shell binary missing), workspace directory does not exist or is not writable, an IOException occurs writing to the new process, or the nested 'Startup command failed' RuntimeException is caught by this same catch block.","commonSituations":"Shell binary not installed or not on PATH in a slim Docker image; workspace directory path misconfigured or lacking write permission; nested 'Startup command failed' surfacing as this message; resource limits preventing process spawn (ulimit, containers without procfs).","solutions":["Inspect the getCause() chain — the root cause (IOException from process start, or the startup-command failure) tells you the real problem.","Verify the configured shell binary exists in the runtime environment (e.g. 'bash' or 'sh' available in the container image).","Ensure the configured workspace directory exists and is readable/writable by the JVM process user.","Fix any failing startup commands (see the nested 'Startup command failed' error) so initialize() completes."],"exampleFix":"// before\nShellSessionManager mgr = new ShellSessionManager(ShellSessionConfig.builder().workspace(\"/does/not/exist\").build());\nmgr.initialize(config);\n\n// after\nFiles.createDirectories(Path.of(\"/workspace\")); // ensure workspace exists first\nShellSessionManager mgr = new ShellSessionManager(ShellSessionConfig.builder().workspace(\"/workspace\").build());\nmgr.initialize(config);","handlingStrategy":"try-catch","validationCode":"// Validate before initialize():\nif (!Files.isDirectory(workspace) || !Files.isWritable(workspace))\n    throw new IllegalStateException(\"Workspace missing or not writable: \" + workspace);\nif (ProcessHandle.of(findShellPid()).isEmpty()) /* or */\nif (!new File(\"/bin/bash\").canExecute()) throw new IllegalStateException(\"Shell binary not available\");","typeGuard":null,"tryCatchPattern":"try {\n    manager.initialize(config);\n} catch (RuntimeException e) {\n    Throwable root = e; while (root.getCause() != null) root = root.getCause();\n    log.error(\"Shell session init failed, root cause: {}\", root.getMessage(), root);\n    // fix env per root cause, then retry\n}","preventionTips":["Verify the shell binary (bash/sh) exists and is executable in the deployment image.","Ensure the workspace directory exists and is writable by the JVM user before initializing.","Always inspect the full cause chain — the wrapper hides the real root cause.","Avoid nested 'Startup command failed' by making startup commands fault-tolerant."],"tags":["shell","process","initialization","workspace"],"backgroundTag":"shell-session-init-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}