--proxied-server-idle-timeout requires --proxied-server

Error message

--proxied-server-idle-timeout requires --proxied-server

What it means

`--proxied-server-idle-timeout` only applies in proxied-server mode; passing it without `--proxied-server` is rejected. The idle timeout controls when the proxy tears down idle connections, so it is meaningless without the proxy (cmd/bd/init.go:488-491).

Source

Thrown at cmd/bd/init.go:490

			}
			if !filepath.IsAbs(serverRootPath) {
				return fmt.Errorf("--proxied-server-root-path must be an absolute path, got %q", serverRootPath)
			}
			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)")

View on GitHub (pinned to 71377f2769)

Solutions

Add `--proxied-server` to the init command.
Export BEADS_DOLT_PROXIED_SERVER=1 so initProxiedServer becomes true.
Remove the `--proxied-server-idle-timeout` flag if not running a proxied server.

Example fix

// before
bd init --proxied-server-idle-timeout 5m
// after
bd init --proxied-server --proxied-server-idle-timeout 5m

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
if [[ -n "$IDLE_TIMEOUT" ]] && [[ -z "$PROXIED" ]]; then
  echo "--proxied-server-idle-timeout requires --proxied-server" >&2; exit 2
fi

Type guard

func timeoutFlagValid(useProxied, timeoutSet bool) bool { return !timeoutSet || useProxied }

Try / catch

if out, err := exec.Command("bd", "init", args...).CombinedOutput(); err != nil {
    if strings.Contains(string(out), "--proxied-server-idle-timeout requires --proxied-server") {
        // add --proxied-server or drop the timeout flag
    }
}

Prevention

Set tuning flags like idle-timeout only in the proxied-mode code path.
Use BEADS_DOLT_PROXIED_SERVER=1 consistently when the environment is proxied.
Review CI job specs after removing mode-enabling env vars.

When it happens

Trigger: Running `bd init --proxied-server-idle-timeout 5m` (or with `=` form) without `--proxied-server`; detected via `idleTimeoutSet && !initProxiedServer`. Also occurs when BEADS_DOLT_PROXIED_SERVER=1 was expected but not set.

Common situations: Tuning scripts that set the timeout flag for all init invocations; combining flags from a proxied-mode snippet into a non-proxied init; CI jobs where the env var enabling proxy mode was dropped from the job spec.

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/1eef52c6dbded117. Report an issue: GitHub.