--proxied-server-idle-timeout must be 0 (never) or a positiv

Error message

--proxied-server-idle-timeout must be 0 (never) or a positive duration, got %s

What it means

The idle timeout must be either 0 (meaning "never time out", mapped internally to proxy.IdleTimeoutNever) or a positive duration. Negative durations are rejected because they have no valid semantics for a connection idle timeout (cmd/bd/init.go:492-497).

Source

Thrown at cmd/bd/init.go:493

			}
			if err := validateProxiedServerRootPath(serverRootPath); err != nil {
				return fmt.Errorf("--proxied-server-root-path %v", err)
			}
		}
		if serverProxyPort != 0 {
			if !initProxiedServer {
				return fmt.Errorf("--proxied-server-port requires --proxied-server")
			}
			if serverProxyPort < 1 || serverProxyPort > 65535 {
				return fmt.Errorf("--proxied-server-port must be between 1 and 65535, got %d", serverProxyPort)
			}
		}
		if idleTimeoutSet {
			if !initProxiedServer {
				return fmt.Errorf("--proxied-server-idle-timeout requires --proxied-server")
			}
			if serverProxyIdleTimeout < 0 {
				return fmt.Errorf("--proxied-server-idle-timeout must be 0 (never) or a positive duration, got %s", serverProxyIdleTimeout)
			}
			if serverProxyIdleTimeout == 0 {
				serverProxyIdleTimeout = proxy.IdleTimeoutNever
			}
		}

		externalProvided := externalHost != "" || externalPort != 0 || externalSocketPath != "" ||
			externalUser != "" ||
			externalTLS || externalTLSCACertPath != "" || externalTLSCertPath != "" || externalTLSKeyPath != "" ||
			externalTLSServerName != "" || externalTLSSkipVerify || externalKeepAlive != 0
		if externalProvided && !initProxiedServer {
			return fmt.Errorf("--proxied-server-external-* flags require --proxied-server")
		}
		if externalProvided && serverConfigPath != "" {
			return fmt.Errorf("--proxied-server-external-* flags cannot be combined with --proxied-server-config-path (external mode has no managed dolt sql-server to configure)")
		}
		if externalProvided && debugMode {
			return fmt.Errorf("--debug cannot be combined with --proxied-server-external-* (debug applies to the managed dolt sql-server only)")

View on GitHub (pinned to 71377f2769)

Solutions

Use a positive duration like 30s, 5m, or 1h.
Use 0 explicitly if connections should never be idled out.
Fix the script/env var that computed the negative value.

Example fix

// before
bd init --proxied-server --proxied-server-idle-timeout -30s
// after
bd init --proxied-server --proxied-server-idle-timeout 5m   // or 0 for "never"

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
# parse Go duration and reject negatives
if [[ "$IDLE_TIMEOUT" == -* ]]; then
  echo "idle timeout must be 0 (never) or positive, got $IDLE_TIMEOUT" >&2; exit 2
fi

Type guard

func validIdleTimeout(d time.Duration) bool { return d >= 0 }

Try / catch

if out, err := exec.Command("bd", "init", args...).CombinedOutput(); err != nil {
    if strings.Contains(string(out), "must be 0 (never) or a positive duration") {
        // replace with positive duration or 0
    }
}

Prevention

Treat 0 as "never", not "immediately"; use positive durations otherwise.
Guard env-derived values against sign errors before passing them on the command line.
Avoid -1 style sentinels; use 0 for "never" per the flag's contract.

When it happens

Trigger: Running `bd init --proxied-server --proxied-server-idle-timeout -30s` (or any negative Go duration) — the check is `serverProxyIdleTimeout < 0`.

Common situations: Sign errors or shell variable interpolation producing a negative value (e.g. `--idle-timeout $NEG_TIMEOUT`); misunderstanding that 0 means "immediately" when it actually means "never"; generated configs with sentinel -1 values.

Understand the failure class

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

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/69cad119e8644b7d. Report an issue: GitHub.