What causes "Failed to initialize shell session" in alibaba/spring-ai-alibaba?

Inspect the logged cause (log.error includes the original exception) to find the underlying failure (missing shell, bad directory, permissions).

alibaba/spring-ai-alibaba · critical · RuntimeException

Failed to initialize shell session

Error message

Failed to initialize shell session

What it means

ShellToolAgentHook.beforeAgent() initializes the shell session manager used by shell tool execution. If sessionManager.initialize(config) throws for any reason, the hook logs the error and rethrows it as a RuntimeException ("Failed to initialize shell session") so agent startup aborts before any shell command runs.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/hook/shelltool/ShellToolAgentHook.java:92

		return new Builder();
	}

	@Override
	public CompletableFuture<Map<String, Object>> beforeAgent(OverAllState state, RunnableConfig config) {
		ShellSessionManager sessionManager = getSessionManager();
		if (sessionManager == null) {
			log.warn("ShellToolAgentHook: No ShellTool2 injected, skipping initialization");
			return CompletableFuture.completedFuture(new HashMap<>());
		}

		log.info("ShellToolAgentHook: Initializing shell session before agent execution");

		try {
			sessionManager.initialize(config);
			log.info("Shell session initialized successfully");
		} catch (Exception e) {
			log.error("Failed to initialize shell session", e);
			throw new RuntimeException("Failed to initialize shell session", e);
		}

		return CompletableFuture.completedFuture(new HashMap<>());
	}

	@Override
	public CompletableFuture<Map<String, Object>> afterAgent(OverAllState state, RunnableConfig config) {
		ShellSessionManager sessionManager = getSessionManager();
		if (sessionManager == null) {
			log.warn("ShellToolAgentHook: No ShellTool2 injected, skipping cleanup");
			return CompletableFuture.completedFuture(new HashMap<>());
		}

		log.info("ShellToolAgentHook: Cleaning up shell session after agent execution");

		try {
			sessionManager.cleanup(config);
			log.info("Shell session cleaned up successfully");

View on GitHub (pinned to f82da0b50f)

Solutions

Inspect the logged cause (log.error includes the original exception) to find the underlying failure (missing shell, bad directory, permissions).
Verify the configured working directory exists and is writable by the process user before starting the agent.
Ensure the shell binary (e.g. /bin/bash) exists in the runtime image; adjust ShellToolConfig accordingly.
Wrap beforeAgent/agent startup in a health check that initializes the session early and fails fast with a clear message.

Example fix

// before
Files.createDirectories(Paths.get("/app/workspace")); // possibly missing/unwritable
// after
Path dir = Paths.get(System.getProperty("java.io.tmpdir"), "agent-shell");
Files.createDirectories(dir);
ShellToolConfig config = ShellToolConfig.builder().workingDirectory(dir).build();

Defensive patterns

Strategy: try-catch

Validate before calling

Path wd = Paths.get(config.getWorkingDirectory());
if (!Files.isDirectory(wd) || !Files.isWritable(wd)) {
    throw new IllegalStateException("Shell working directory missing or unwritable: " + wd);
}
if (new File("/bin/bash").exists() == false && System.getenv("SHELL") == null) {
    throw new IllegalStateException("No shell binary available");
}

Try / catch

try {
    agent.invoke(inputs);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Failed to initialize shell session")) {
        // inspect e.getCause() for the root reason; fix env and restart
    } else throw e;
}

Prevention

Verify working directory existence/writability at startup
Bake the required shell binary into container images
Run a shell smoke test in CI for deployment targets
Always log and inspect the cause chain of this wrapper exception

When it happens

Trigger: Agent start with ShellToolAgentHook registered when the shell session cannot be created: working directory does not exist or is not writable, the shell executable is missing, timeout/environment config is invalid, or the underlying process spawn fails.

Common situations: Deploying to containers/images without bash or the expected shell; running under a user without write access to the configured workspace directory; Windows/Unix path mismatches; restrictive sandbox environments blocking process creation.

Related errors

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