What causes "codex.live-media-relay.max-sessions must not be negative" in router-for-me/CLIProxyAPI?

Set max-sessions to a positive limit, or remove the key / set 0 to use DefaultCodexLiveMediaMaxSessions

codex.live-media-relay.max-sessions must not be negative

Error message

codex.live-media-relay.max-sessions must not be negative

What it means

Validation error for the codex.live-media-relay config: enabled is true and max-sessions was set to a negative number. Negative session limits are meaningless (zero already means 'use the default'), so Validate() rejects them before the relay starts.

Source

Thrown at internal/config/codex_live.go:71

	*c = CodexLiveMediaRelayConfig(decoded)
	return nil
}

// EffectiveMaxSessions returns the configured media session limit.
func (c CodexLiveMediaRelayConfig) EffectiveMaxSessions() int {
	if c.MaxSessions > 0 {
		return c.MaxSessions
	}
	return DefaultCodexLiveMediaMaxSessions
}

// Validate verifies the Codex Live media relay configuration.
func (c CodexLiveMediaRelayConfig) Validate() error {
	if !c.Enabled {
		return nil
	}
	if c.MaxSessions < 0 {
		return errors.New("codex.live-media-relay.max-sessions must not be negative")
	}
	if publicIP := strings.TrimSpace(c.PublicIP); publicIP != "" && net.ParseIP(publicIP) == nil {
		return fmt.Errorf("codex.live-media-relay.public-ip is invalid: %q", publicIP)
	}
	if (c.UDPPortMin == 0) != (c.UDPPortMax == 0) {
		return errors.New("codex.live-media-relay UDP port minimum and maximum must both be set")
	}
	if c.UDPPortMin > c.UDPPortMax {
		return errors.New("codex.live-media-relay.udp-port-min must not exceed udp-port-max")
	}
	if c.UDPPortMin != 0 {
		availablePorts := int(c.UDPPortMax) - int(c.UDPPortMin) + 1
		requiredPorts := c.EffectiveMaxSessions() * 2
		if availablePorts < requiredPorts {
			return fmt.Errorf("codex.live-media-relay UDP range requires at least %d ports for %d sessions", requiredPorts, c.EffectiveMaxSessions())
		}
	}
	for serverIndex, server := range c.ICEServers {

View on GitHub (pinned to 78f0c4079e)

Solutions

Set max-sessions to a positive limit, or remove the key / set 0 to use DefaultCodexLiveMediaMaxSessions
Re-validate the config and restart

Example fix

# before
codex:
  live-media-relay:
    enabled: true
    max-sessions: -1
# after
codex:
  live-media-relay:
    enabled: true
    max-sessions: 16

Defensive patterns

Strategy: validation

Validate before calling

if cfg.Codex.LiveMediaRelay.Enabled && cfg.Codex.LiveMediaRelay.MaxSessions < 0 {
    return fmt.Errorf("reject config: max-sessions=%d is negative", cfg.Codex.LiveMediaRelay.MaxSessions)
}

Try / catch

if err := relayCfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "max-sessions must not be negative") {
        return errors.New("config fix: set max-sessions >= 0 (0 = default limit)")
    }
    return err
}

Prevention

Use 0 for the default limit instead of -1
Run config validation in CI with the same binary version that serves production

When it happens

Trigger: Config with codex.live-media-relay.enabled: true and max-sessions: -1 (or any negative value).

Common situations: Typo in config, or copied snippets using -1 as an 'unlimited' convention from other tools.

Related errors

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/d579a27867515534. Report an issue: GitHub.