alibaba/spring-ai-alibaba · error · RuntimeException

Startup command failed:

Error message

Startup command failed: 

What it means

During ShellSessionManager.initialize(), each configured startup command is executed in the new shell session. If a command times out or exits with a non-zero exit code, the manager throws this RuntimeException naming the command and its exit code, then aborts session creation. It exists so a broken startup script fails fast instead of leaving a half-initialized session.

Source

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

			ShellSession session = new ShellSession(workspace, shellCommand, environment, terminationTimeout);
			session.start();
			config.context().put(SESSION_INSTANCE_CONTEXT_KEY, session);

			// 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);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Run the failing command manually in an equivalent shell to see why it exits non-zero, and fix it (correct path, missing file, permissions).
2. Increase the startupTimeout configuration if the command is legitimate but slow.
3. Remove or make fault-tolerant non-essential startup commands, e.g. append '|| true' so a non-zero exit does not abort session init.
4. Catch the RuntimeException and inspect the message (it includes the command and exit code) to identify which startup command failed.

Example fix

// before
config.setStartupCommands(List.of("source /app/venv/bin/activate"));

// after
config.setStartupCommands(List.of("source /app/venv/bin/activate || true")); // tolerate missing venv
// or increase timeout
config.setStartupTimeout(60_000L);

// Before startup, verify each command succeeds standalone:
for (String cmd : startupCommands) {
    Process p = new ProcessBuilder("sh", "-c", cmd).start();
    if (p.waitFor() != 0) throw new IllegalStateException("Startup command will fail: " + cmd);
}

try {
    manager.initialize(config);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Startup command failed")) {
        // e.getMessage() names the failing command and exit code; fix or drop it
    }
}

When it happens

Trigger: A startup command in the configured startupCommands list returns exit code != 0, or exceeds startupTimeout and is reported as timed out, while initialize() runs (directly or via beforeAgent hook / executeCommand lazy init).

Common situations: Typo or wrong path in a startup command like 'cd /nonexistent'; 'source venv/bin/activate' failing because the venv does not exist in the workspace; commands that require TTY interaction; startupTimeout too short for slow commands (package installs, container boots).

Related errors

• Command timed out, restarting session
• Failed to initialize shell session
• 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/f0a8f3fd73a33e51. Report an issue: GitHub.