{"record":{"id":"ccc58e55daa9f411","repo":"wavetermdev/waveterm","slug":"error-starting-controller-w","errorCode":null,"errorMessage":"error starting controller: %w","messagePattern":"error starting controller: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/blockcontroller/blockcontroller.go","lineNumber":280,"sourceCode":"\t}\n\n\t// Check if we need to start/restart\n\tstatus := controller.GetRuntimeStatus()\n\tif status.ShellProcStatus == Status_Init {\n\t\t// For shell/cmd, check connection status first (for non-local connections)\n\t\tif controllerName == BlockController_Shell || controllerName == BlockController_Cmd {\n\t\t\tif !conncontroller.IsLocalConnName(connName) {\n\t\t\t\terr = CheckConnStatus(blockId)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn fmt.Errorf(\"cannot start shellproc: %w\", err)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Start controller\n\t\terr = controller.Start(ctx, blockData.Meta, rtOpts, force)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"error starting controller: %w\", err)\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc GetBlockControllerRuntimeStatus(blockId string) *BlockControllerRuntimeStatus {\n\tcontroller := getController(blockId)\n\tif controller == nil {\n\t\treturn nil\n\t}\n\treturn controller.GetRuntimeStatus()\n}\n\nfunc DestroyBlockController(blockId string) {\n\tcontroller := getController(blockId)\n\tif controller == nil {\n\t\treturn","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/blockcontroller/blockcontroller.go#L262-L298","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped %w cause to identify the underlying start failure","Verify the shell/command path and cwd in the block meta exist on the target host","Reset the block meta to defaults and retry with force=true","For remote blocks, confirm the connection supports exec and credentials are valid"],"exampleFix":"// before\nmeta: { \"cmdshell\": \"/usr/bin/zshh\" }\n// after\nmeta: { \"cmdshell\": \"/usr/bin/zsh\" }","handlingStrategy":"try-catch","validationCode":"if shellPath := meta.GetString(\"cmdshell\", \"\"); shellPath != \"\" {\n    if _, err := os.Stat(shellPath); err != nil { /* fix meta */ }\n}","typeGuard":null,"tryCatchPattern":"if err := ResyncController(ctx, tabId, blockId, rtOpts, false); err != nil && strings.Contains(err.Error(), \"error starting controller\") {\n    log.Printf(\"controller start failed: %v\", err) // inspect %w cause\n}","preventionTips":["Verify shell/cwd paths in block meta exist on the target host","Keep meta keys matching current schema version","Check remote exec support and credentials before starting remote shells"],"tags":["process","startup","blockcontroller"],"backgroundTag":"process-start-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}