{"record":{"id":"8e33c827930e0e4b","repo":"chenhg5/cc-connect","slug":"tmux-session-option-is-required-name-of-the-tm","errorCode":null,"errorMessage":"tmux: 'session' option is required (name of the tmux session to attach)","messagePattern":"tmux: 'session' option is required \\(name of the tmux session to attach\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/tmux/tmux.go","lineNumber":46,"sourceCode":"\tshell           string\n\tinitCmd         string // command to run once after a new session is created (e.g. \"claude\")\n\tstartupWaitMs   int    // milliseconds to wait after init_command before accepting messages\n\tpromptPat       string\n\tpollMs          int\n\tstripInputBlock bool     // strip the ───/❯/─── input area block from output\n\tstripPatterns   []string // per-line regex patterns to strip from output\n\t// windowPerSession, when true, gives each cc-connect session its own tmux\n\t// window (and thus its own init_command/agent instance) instead of sharing\n\t// the single session:pane target. Required for true per-session isolation\n\t// (e.g. session_scope = \"thread\" on the platform).\n\twindowPerSession bool\n\tmu               sync.RWMutex\n}\n\nfunc New(opts map[string]any) (core.Agent, error) {\n\tsessionName, _ := opts[\"session\"].(string)\n\tif sessionName == \"\" {\n\t\treturn nil, fmt.Errorf(\"tmux: 'session' option is required (name of the tmux session to attach)\")\n\t}\n\n\tpane, _ := opts[\"pane\"].(string)\n\tif pane == \"\" {\n\t\tpane = \"0\"\n\t}\n\n\tworkDir, _ := opts[\"work_dir\"].(string)\n\tif workDir == \"\" {\n\t\tworkDir = \".\"\n\t}\n\n\tautoCreate := true\n\tif v, ok := opts[\"auto_create\"].(bool); ok {\n\t\tautoCreate = v\n\t}\n\n\tshell, _ := opts[\"shell\"].(string)","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/agent/tmux/tmux.go#L28-L64","documentation":"tmux agent's New() validates its options map and refuses to construct the agent when the required 'session' option is absent or empty. The agent attaches to a named tmux session, so without it no target can be determined. This is a constructor-time configuration validation error, not a runtime tmux error.","triggerScenarios":"Creating the agent via core.CreateAgent(\"tmux\", opts) (or directly New(opts)) with opts missing the 'session' key, or with session set to \"\" (e.g. empty TOML value in config.toml).","commonSituations":"config.toml [[agents]] block for the tmux agent missing options.session; session name interpolated from an unset env var resulting in \"\"; copy-pasting an example config that omitted the field.","solutions":["Add options.session = \"<tmux-session-name>\" to the tmux agent's config block","Ensure the value is non-empty after any variable interpolation","See agent/tmux docs for the full options set (pane, work_dir, auto_create, shell, window_per_session)"],"exampleFix":"// before (config.toml)\n[[agents]]\ntype = \"tmux\"\n[agents.options]\npane = \"0\"\n\n// after\n[[agents]]\ntype = \"tmux\"\n[agents.options]\nsession = \"my-session\"\npane = \"0\"","handlingStrategy":"validation","validationCode":"func validateTmuxOpts(opts map[string]any) error {\n    s, _ := opts[\"session\"].(string)\n    if strings.TrimSpace(s) == \"\" { return errors.New(\"tmux agent requires options.session\") }\n    return nil\n}","typeGuard":"func sessionOpt(opts map[string]any) (string, bool) {\n    s, ok := opts[\"session\"].(string)\n    return s, ok && s != \"\"\n}","tryCatchPattern":"a, err := tmux.New(opts)\nif err != nil && strings.Contains(err.Error(),\"'session' option is required\") {\n    return fmt.Errorf(\"config: tmux agent block missing options.session: %w\", err)\n}","preventionTips":["Always set options.session in the tmux agent config block","Validate config at startup with a dry-run parse","Avoid interpolating unset env vars into session names","Copy complete examples from config.example.toml"],"tags":["go","config","validation","tmux"],"backgroundTag":"missing-required-option","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}