{"record":{"id":"81aae68d6830b7d4","repo":"wavetermdev/waveterm","slug":"unknown-connection-type-for-conn-q-s","errorCode":null,"errorMessage":"unknown connection type for conn %q: %s","messagePattern":"unknown connection type for conn %q: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/blockcontroller/shellcontroller.go","lineNumber":515,"sourceCode":"\t\t\t\tProcRoute: true,\n\t\t\t\tSockName:  sockName,\n\t\t\t\tBlockId:   bc.BlockId,\n\t\t\t}\n\t\t\tjwtStr, err := wshutil.MakeClientJWTToken(rpcContext)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"error making jwt token: %w\", err)\n\t\t\t}\n\t\t\tswapToken.RpcContext = &rpcContext\n\t\t\tswapToken.Env[wshutil.WaveJwtTokenVarName] = jwtStr\n\t\t}\n\t\tcmdOpts.ShellPath = connUnion.ShellPath\n\t\tcmdOpts.ShellOpts = getLocalShellOpts(blockMeta)\n\t\tshellProc, err = shellexec.StartLocalShellProc(logCtx, rc.TermSize, cmdStr, cmdOpts, remoteName)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t} else {\n\t\treturn nil, fmt.Errorf(\"unknown connection type for conn %q: %s\", remoteName, connUnion.ConnType)\n\t}\n\tbc.UpdateControllerAndSendUpdate(func() bool {\n\t\tbc.ShellProc = shellProc\n\t\tbc.ProcStatus = Status_Running\n\t\treturn true\n\t})\n\treturn shellProc, nil\n}\n\nfunc (bc *ShellController) manageRunningShellProcess(shellProc *shellexec.ShellProc, rc *RunShellOpts, blockMeta waveobj.MetaMapType) error {\n\tshellInputCh := make(chan *BlockInputUnion, 32)\n\tbc.ShellInputCh = shellInputCh\n\n\tgo func() {\n\t\t// handles regular output from the pty (goes to the blockfile and xterm)\n\t\tdefer func() {\n\t\t\tpanichandler.PanicHandler(\"blockcontroller:shellproc-pty-read-loop\", recover())\n\t\t}()","sourceCodeStart":497,"sourceCodeEnd":533,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/blockcontroller/shellcontroller.go#L497-L533","documentation":"Terminal else-branch of the connection-type dispatch in setupAndStartShellProcess: ConnUnion.ConnType was neither ConnType_Wsl, ConnType_Ssh, nor ConnType_Local. This is an internal invariant breach — getConnUnion should only ever produce those three types.","triggerScenarios":"A ConnUnion with an unset (zero-value) or foreign ConnType reaches the shell-start dispatch, e.g. after a future/modified getConnUnion adds a new ConnType without updating setupAndStartShellProcess, or a partially-initialized ConnUnion is passed in.","commonSituations":"Custom/experimental builds extending connection types without updating the shell startup switch; race where ConnUnion zero-value struct is used before getConnUnion populated it; deserialized session state carrying an obsolete conn type code.","solutions":["Verify remoteName resolves through getConnUnion to a known ConnType before calling setupAndStartShellProcess","Update the dispatch (and getConnUnion) so every new ConnType has a corresponding start branch","Re-create the block/session state if a stale conn type code was restored from disk","File a bug with the logged remoteName and ConnType if this occurs on a stock build"],"exampleFix":"// before: adding a new conn type but not the start branch\nrtn.ConnType = ConnType_Docker // new type, no handling in setupAndStartShellProcess\n\n// after: handle it or reject early\nif connUnion.ConnType != ConnType_Wsl && connUnion.ConnType != ConnType_Ssh && connUnion.ConnType != ConnType_Local {\n    return nil, fmt.Errorf(\"unsupported conn type %s\", connUnion.ConnType)\n}","handlingStrategy":"validation","validationCode":"if connUnion.ConnType != ConnType_Wsl && connUnion.ConnType != ConnType_Ssh && connUnion.ConnType != ConnType_Local {\n    return fmt.Errorf(\"refusing to start shell: invalid conn type %s\", connUnion.ConnType)\n}","typeGuard":"func validConnType(t ConnType) bool {\n    return t == ConnType_Wsl || t == ConnType_Ssh || t == ConnType_Local\n}","tryCatchPattern":"proc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)\nif err != nil && strings.Contains(err.Error(), \"unknown connection type for conn\") {\n    // re-resolve via getConnUnion or recreate the block\n}","preventionTips":["When adding a new ConnType, update every dispatch site (compiler exhaustiveness checks help)","Never pass zero-value ConnUnion structs; always consume getConnUnion's error first","Validate conn type codes when deserializing saved session state"],"tags":["internal","dispatch","connection-type"],"backgroundTag":"unknown-connection-type","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}