chenhg5/cc-connect · error

config: %s.agent_session_idle_timeout_mins must be >= 0

Error message

config: %s.agent_session_idle_timeout_mins must be >= 0

What it means

The optional agent_session_idle_timeout_mins setting bounds how long an agent session may stay idle before being timed out; negative values are invalid. The validator checks it only when present (pointer non-nil) and rejects any negative duration.

Source

Thrown at config/config.go:1054

		}
		for j, p := range proj.Platforms {
			if p.Type == "" {
				return fmt.Errorf("config: %s.platforms[%d].type is required", prefix, j)
			}
		}
		if proj.Mode == "multi-workspace" {
			if proj.BaseDir == "" {
				return fmt.Errorf("project %q: multi-workspace mode requires base_dir", proj.Name)
			}
			if _, ok := proj.Agent.Options["work_dir"]; ok {
				return fmt.Errorf("project %q: multi-workspace mode conflicts with agent work_dir (use base_dir instead)", proj.Name)
			}
		}
		if proj.ResetOnIdleMins != nil && *proj.ResetOnIdleMins < 0 {
			return fmt.Errorf("config: %s.reset_on_idle_mins must be >= 0", prefix)
		}
		if proj.AgentSessionIdleTimeoutMins != nil && *proj.AgentSessionIdleTimeoutMins < 0 {
			return fmt.Errorf("config: %s.agent_session_idle_timeout_mins must be >= 0", prefix)
		}
		if err := validateRunAsUser(prefix, proj.RunAsUser); err != nil {
			return err
		}
		if err := validateRunAsEnv(prefix, proj.RunAsEnv); err != nil {
			return err
		}
		if err := validateReferenceConfig(prefix, proj.References); err != nil {
			return err
		}
		if err := validateUsersConfig(prefix, proj.Users); err != nil {
			return err
		}
		if err := validateDisplayConfig(prefix+".display", proj.Display); err != nil {
			return err
		}
	}
	return nil

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set a non-negative value in minutes, e.g. agent_session_idle_timeout_mins = 60
2. Remove the key to use the built-in default idle timeout
3. If 'never timeout' is desired, check docs for a supported sentinel or a very large value

Example fix

// before
[[projects]]
name = "my-app"
agent_session_idle_timeout_mins = -1
// after
[[projects]]
name = "my-app"
agent_session_idle_timeout_mins = 60

if proj.AgentSessionIdleTimeoutMins != nil && *proj.AgentSessionIdleTimeoutMins < 0 {
    return fmt.Errorf("agent_session_idle_timeout_mins must be >= 0")
}

When it happens

Trigger: Setting agent_session_idle_timeout_mins = -10 on a [[projects]] entry, so the nil-check passes but *proj.AgentSessionIdleTimeoutMins < 0 triggers the error.

Common situations: Using -1 as a 'never timeout' sentinel that this field does not support; sign typos; templating tools emitting negative defaults for unset durations.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• tmux: 'session' option is required (name of the tmux session
• config: relay.visibility must be "full", "summary", or "none
• config: at least one [[projects]] entry is required
• config: %s.name is required
• config: %s.agent.type is required

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