wavetermdev/waveterm · error

cannot start shellproc: %w

Error message

cannot start shellproc: %w

What it means

Before starting a shell/cmd controller, ResyncController checks the remote connection state when the block targets a non-local connection. If CheckConnStatus reports the connection is not ready, the failure is wrapped as 'cannot start shellproc: %w'. The shell process was never started because the underlying connection is unavailable.

Source

Thrown at pkg/blockcontroller/blockcontroller.go:272

		case BlockController_Tsunami:
			controller = MakeTsunamiController(tabId, blockId, connName)
			registerController(blockId, controller)

		default:
			return fmt.Errorf("unknown controller type %q", controllerName)
		}
	}

	// Check if we need to start/restart
	status := controller.GetRuntimeStatus()
	if status.ShellProcStatus == Status_Init {
		// For shell/cmd, check connection status first (for non-local connections)
		if controllerName == BlockController_Shell || controllerName == BlockController_Cmd {
			if !conncontroller.IsLocalConnName(connName) {
				err = CheckConnStatus(blockId)
				if err != nil {
					return fmt.Errorf("cannot start shellproc: %w", err)
				}
			}
		}

		// Start controller
		err = controller.Start(ctx, blockData.Meta, rtOpts, force)
		if err != nil {
			return fmt.Errorf("error starting controller: %w", err)
		}
	}

	return nil
}

func GetBlockControllerRuntimeStatus(blockId string) *BlockControllerRuntimeStatus {
	controller := getController(blockId)
	if controller == nil {
		return nil

View on GitHub (pinned to a4447c1563)

Solutions

1. Ensure the connection is active before opening the block (connect via the connections UI or conncontroller)
2. Fix the block's meta 'connection' value to a valid, existing connection name or empty for local
3. Retry the resync after the connection finishes connecting
4. Check network/SSH credentials if the connection itself fails to establish

Example fix

// before
// block meta: { "connection": "old-ssh-profile" }
// after
// reconnect first:
err := conncontroller.MakeConn(ctx, "myserver")
if err == nil { ResyncController(ctx, tabId, blockId, rtOpts, false) }

if !conncontroller.IsLocalConnName(connName) {
    if err := CheckConnStatus(blockId); err != nil { /* wait/reconnect */ }
}

for i := 0; i < 3; i++ {
    if err := ResyncController(ctx, tabId, blockId, rtOpts, false); err == nil || !strings.Contains(err.Error(), "cannot start shellproc") { break }
    time.Sleep(2 * time.Second)
}

When it happens

Trigger: Starting a shell/cmd block whose meta connection name refers to a remote SSH connection that is disconnected, connecting, or errored — CheckConnStatus returns a non-nil error.

Common situations: SSH connection dropped or not yet established when a terminal block auto-restarts on app launch; wrong connName in block meta pointing at a removed connection profile; network down.

Related errors

• cannot parse connection name: %w
• getting ssh connection status: %w
• connecting connection: %w
• no connection found
• connection %q not found

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/411a329e03e61609. Report an issue: GitHub.