wavetermdev/waveterm · error

error starting controller: %w

Error message

error starting controller: %w

What it means

After connection checks pass, ResyncController calls controller.Start(ctx, blockData.Meta, rtOpts, force). Any error the specific controller (shell, cmd, tsunami, etc.) returns during startup is wrapped as 'error starting controller: %w'. The controller itself failed to initialize its process/runtime.

Source

Thrown at pkg/blockcontroller/blockcontroller.go:280

	}

	// 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
	}
	return controller.GetRuntimeStatus()
}

func DestroyBlockController(blockId string) {
	controller := getController(blockId)
	if controller == nil {
		return

View on GitHub (pinned to a4447c1563)

Solutions

1. Read the wrapped %w cause to identify the underlying start failure
2. Verify the shell/command path and cwd in the block meta exist on the target host
3. Reset the block meta to defaults and retry with force=true
4. For remote blocks, confirm the connection supports exec and credentials are valid

Example fix

// before
meta: { "cmdshell": "/usr/bin/zshh" }
// after
meta: { "cmdshell": "/usr/bin/zsh" }

if shellPath := meta.GetString("cmdshell", ""); shellPath != "" {
    if _, err := os.Stat(shellPath); err != nil { /* fix meta */ }
}

if err := ResyncController(ctx, tabId, blockId, rtOpts, false); err != nil && strings.Contains(err.Error(), "error starting controller") {
    log.Printf("controller start failed: %v", err) // inspect %w cause
}

When it happens

Trigger: controller.Start failing for any reason: shell binary not found, working directory missing, invalid runtime opts in block meta, PTY allocation failure, or remote command spawn errors.

Common situations: Shell path misconfigured (meta cmd/shell points to a nonexistent binary); cwd deleted; invalid MetaKey_CustomShell; resource limits preventing PTY spawn; remote host rejecting the exec request.

Related errors

• procinfo: process not found
• setting auth key: %v
• error getting client: %v
• error setting up connserver rpc client: %v
• error getting jwt public key: %v

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