chenhg5/cc-connect · error

tmux: session %q does not exist and auto_create is disabled

Error message

tmux: session %q does not exist and auto_create is disabled

What it means

StartSession checks tmuxSessionExists before touching tmux and refuses to start when the configured session is absent and the 'auto_create' option is not enabled. The agent attaches to pre-existing tmux sessions by default, so it will not silently create infrastructure the user did not ask for.

Source

Thrown at agent/tmux/tmux.go:178

	// Decide which tmux window this session drives:
	//   - window_per_session: a dedicated window per cc-connect session (true
	//     isolation; each gets its own init_command/agent instance).
	//   - else, when workDir is a real path: a window named after the directory
	//     so each workspace gets its own instance.
	//   - else: the legacy session:pane target.
	// windowForSession may allocate a fresh window name when sessionID is empty;
	// the returned ID is persisted by the engine so resumes reuse the same window.
	windowName, effectiveSessionID := a.windowForSession(sessionName, pane, workDir, sessionID)
	sessionID = effectiveSessionID
	target := sessionName + ":" + windowName

	sessionExists := tmuxSessionExists(sessionName)
	windowExists := sessionExists && tmuxWindowExists(target)

	if !sessionExists {
		if !autoCreate {
			return nil, fmt.Errorf("tmux: session %q does not exist and auto_create is disabled", sessionName)
		}
		if err := createTmuxSession(sessionName, windowName, workDir, shell); err != nil {
			return nil, fmt.Errorf("tmux: create session %q: %w", sessionName, err)
		}
		slog.Info("tmux: created session", "session", sessionName, "window", windowName, "work_dir", workDir)
	} else if !windowExists && windowName != pane {
		// Session exists but this workspace window does not yet — create it.
		if err := createTmuxWindow(sessionName, windowName, workDir); err != nil {
			return nil, fmt.Errorf("tmux: create window %q in session %q: %w", windowName, sessionName, err)
		}
		slog.Info("tmux: created window", "session", sessionName, "window", windowName, "work_dir", workDir)
	}

	newPane := !sessionExists || (!windowExists && windowName != pane)
	if newPane {
		// Always cd to the workspace directory so the shell (and any init_command)
		// starts in the right place, regardless of tmux's -c flag behaviour.
		if workDir != "" && workDir != "." {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Create the session manually: tmux new-session -d -s <name>
2. Set auto_create = true in the agent's options so cc-connect creates it
3. Verify the session name matches: tmux ls
4. If sessions vanish on reboot, run tmux under a persistent mechanism (systemd user unit with tmux server)

Example fix

// before (config.toml)
[agents.options]
session = "cc-work"

// after
[agents.options]
session = "cc-work"
auto_create = true

exists := exec.Command("tmux", "has-session", "-t", sessionName).Run() == nil
if !exists && !autoCreate { /* pre-create or enable auto_create */ }

if _, err := agent.StartSession(ctx, opts); err != nil && strings.Contains(err.Error(), "auto_create is disabled") {
    return fmt.Errorf("run 'tmux new-session -d -s %s' or set auto_create=true", sessionName)
}

When it happens

Trigger: StartSession (typically triggered by the first user message routed to the tmux agent) where options.session names a tmux session that does not exist and options.auto_create is false/unset.

Common situations: tmux session killed after a reboot or logout (no tmux server running); typo in the session name in config; user forgot to add auto_create = true for an agent meant to own its session.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• tmux: 'session' option is required (name of the tmux session
• tmux: create session %q: %w
• tmux: create window %q in session %q: %w
• parse existing Agy hooks %s: %w
• marshal Agy hooks overlay: %w

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/32069d02783aead6. Report an issue: GitHub.