alibaba/spring-ai-alibaba · error · RuntimeException

Failed to initialize shell session

Error message

Failed to initialize shell session

What it means

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.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/ShellSessionManager.java:145

			// Register in global registry for HITL recovery
			final Path finalWorkspace = workspace;
			config.threadId().ifPresent(threadId -> {
				SESSION_REGISTRY.put(threadId, new SessionEntry(session, finalWorkspace));
				log.debug("Registered shell session in global registry with threadId: {}", threadId);
			});

			log.info("Started shell session in workspace: {}", workspace);

			// Run startup commands
			for (String command : startupCommands) {
				CommandResult result = session.execute(command, startupTimeout, maxOutputLines, maxOutputBytes);
				if (result.isTimedOut() || (result.getExitCode() != null && result.getExitCode() != 0)) {
					throw new RuntimeException("Startup command failed: " + command + ", exit code: " + result.getExitCode());
				}
			}
		} catch (Exception e) {
			cleanup(config);
			throw new RuntimeException("Failed to initialize shell session", e);
		}
	}

	/**
	 * Clean up shell session.
	 * This removes the session from both the context and the global registry.
	 */
	public void cleanup(RunnableConfig config) {
		try {
			// Try to get session from context first, then from registry
			ShellSession session = (ShellSession) config.context().get(SESSION_INSTANCE_CONTEXT_KEY);
			if (session == null) {
				session = getSessionFromRegistry(config);
			}
			if (session != null) {
				// Run shutdown commands
				for (String command : shutdownCommands) {
					try {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect the getCause() chain — the root cause (IOException from process start, or the startup-command failure) tells you the real problem.
2. Verify the configured shell binary exists in the runtime environment (e.g. 'bash' or 'sh' available in the container image).
3. Ensure the configured workspace directory exists and is readable/writable by the JVM process user.
4. Fix any failing startup commands (see the nested 'Startup command failed' error) so initialize() completes.

Example fix

// before
ShellSessionManager mgr = new ShellSessionManager(ShellSessionConfig.builder().workspace("/does/not/exist").build());
mgr.initialize(config);

// after
Files.createDirectories(Path.of("/workspace")); // ensure workspace exists first
ShellSessionManager mgr = new ShellSessionManager(ShellSessionConfig.builder().workspace("/workspace").build());
mgr.initialize(config);

// Validate before initialize():
if (!Files.isDirectory(workspace) || !Files.isWritable(workspace))
    throw new IllegalStateException("Workspace missing or not writable: " + workspace);
if (ProcessHandle.of(findShellPid()).isEmpty()) /* or */
if (!new File("/bin/bash").canExecute()) throw new IllegalStateException("Shell binary not available");

try {
    manager.initialize(config);
} catch (RuntimeException e) {
    Throwable root = e; while (root.getCause() != null) root = root.getCause();
    log.error("Shell session init failed, root cause: {}", root.getMessage(), root);
    // fix env per root cause, then retry
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Startup command failed:
• Shell session not initialized. Call initialize() before exec
• Failed to restart shell session
• Shell session is not running
• Failed to execute command

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/0843e28d944ccd7a. Report an issue: GitHub.