agent_timeout must be >= 0 (got %s); use 0s to disable the c

Error message

agent_timeout must be >= 0 (got %s); use 0s to disable the cap or "" to clear the persisted value

What it means

After parsing, agent_timeout rejects negative durations. Unlike the other duration knobs, zero ('0s') is allowed here because it explicitly disables the agent wall-clock cap; only values below zero are invalid.

Source

Thrown at server/cmd/multica/cmd_config.go:227

		if err := assignPositiveDuration(&cfg.HeartbeatInterval, key, value); err != nil {
			return err
		}
	case "agent_timeout":
		// agent_timeout is the one duration knob where "0s" is a
		// meaningful persisted value (it explicitly disables the
		// wall-clock cap; see cli.CLIConfig.AgentTimeout). Store the raw
		// string via a pointer so we can distinguish "not set" (nil)
		// from "disabled" (non-nil, "0s") and any positive value.
		if value == "" {
			cfg.AgentTimeout = nil
			return nil
		}
		d, err := time.ParseDuration(value)
		if err != nil {
			return fmt.Errorf("agent_timeout must be a Go duration (e.g. 10m, 0s to disable): %w", err)
		}
		if d < 0 {
			return fmt.Errorf("agent_timeout must be >= 0 (got %s); use 0s to disable the cap or \"\" to clear the persisted value", d)
		}
		s := value
		cfg.AgentTimeout = &s
	case "codex_semantic_inactivity_timeout":
		if err := assignPositiveDuration(&cfg.CodexSemanticInactivityTimeout, key, value); err != nil {
			return err
		}
	case "codex_handshake_timeout":
		if err := assignPositiveDuration(&cfg.CodexHandshakeTimeout, key, value); err != nil {
			return err
		}
	case "disable_auto_update":
		if err := assignBool(&cfg.DisableAutoUpdate, key, value); err != nil {
			return err
		}
	case "auto_update_check_interval":
		if err := assignPositiveDuration(&cfg.AutoUpdateCheckInterval, key, value); err != nil {
			return err

View on GitHub (pinned to 2c0912b6ec)

Solutions

Use a positive duration (`10m`) or `0s` to disable the cap.
Use `""` to clear the persisted value and fall back to env/default.

Example fix

# before
multica config set agent_timeout -5m
# after
multica config set agent_timeout 0s

Defensive patterns

Strategy: validation

Validate before calling

# normalize intent before setting
if [[ "$VAL" == -* ]]; then VAL="0s"; fi   # 'disable' instead of negative
multica config set agent_timeout "$VAL"

Prevention

Express 'no cap' as 0s, never as a negative duration.
Assert duration >= 0 in any wrapper that computes agent_timeout.

When it happens

Trigger: `multica config set agent_timeout -5m`, or a computed duration that underflows below zero.

Common situations: Scripted timeouts derived from subtraction; sign typos.

Understand the failure class

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

Related errors

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/ff38b734d0e24860. Report an issue: GitHub.