--proxied-server-external-* flags require --proxied-server

Error message

--proxied-server-external-* flags require --proxied-server

What it means

The `--proxied-server-external-*` flag family configures an externally managed dolt sql-server (host, port, socket, user, TLS options, keep-alive) for the proxy to connect to. These flags are only honored in proxied-server mode; if any of them is set without `--proxied-server`, init rejects the whole set with this single error (cmd/bd/init.go:500-506).

Source

Thrown at cmd/bd/init.go:505

		}
		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)")
		}
		var externalConfig *configfile.ExternalDoltConfig
		if externalProvided {
			cfg := configfile.ExternalDoltConfig{
				Host:            externalHost,
				Port:            externalPort,
				Socket:          externalSocketPath,
				User:            externalUser,
				TLSRequired:     externalTLS,
				TLSCACert:       externalTLSCACertPath,
				TLSCert:         externalTLSCertPath,
				TLSKey:          externalTLSKeyPath,

View on GitHub (pinned to 71377f2769)

Solutions

Add `--proxied-server` to the init command along with the external flags.
Set BEADS_DOLT_PROXIED_SERVER=1 in the environment.
Remove the external-* flags if you are not running proxied-server mode.

Example fix

// before
bd init --proxied-server-external-host db.example.com --proxied-server-external-port 3307
// after
bd init --proxied-server --proxied-server-external-host db.example.com --proxied-server-external-port 3307

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
if [[ -n "$EXT_HOST$EXT_SOCKET$EXT_USER" || -n "$EXT_TLS_FLAGS" ]] && [[ -z "$PROXIED" ]]; then
  echo "--proxied-server-external-* flags require --proxied-server" >&2; exit 2
fi

Type guard

func externalFlagsValid(useProxied bool, externalSet bool) bool { return !externalSet || useProxied }

Try / catch

if out, err := exec.Command("bd", "init", args...).CombinedOutput(); err != nil {
    if strings.Contains(string(out), "--proxied-server-external-* flags require --proxied-server") {
        // add --proxied-server or drop external flags
    }
}

Prevention

Always pair the external-* connection flags with --proxied-server in deployment helpers.
Keep the mode toggle and dependent flags in one function/config block.
Document that external dolt servers still require proxied-server mode in runbooks.

When it happens

Trigger: Any of externalHost != "", externalPort != 0, externalSocketPath != "", externalUser != "", externalTLS, any external TLS path/server-name flag, skip-verify, or keep-alive set, while initProxiedServer is false (no `--proxied-server` flag and BEADS_DOLT_PROXIED_SERVER != 1).

Common situations: Connecting bd to a pre-existing dolt sql-server but forgetting that external mode still requires `--proxied-server`; scripts that set external connection flags per-environment while the mode toggle lives elsewhere; docs examples copied partially.

Related errors

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