gastownhall/beads · error

--proxied-server-root-path requires --proxied-server

Error message

--proxied-server-root-path requires --proxied-server

What it means

`bd init` validates that proxied-server related flags are only used together with `--proxied-server`. When `--proxied-server-root-path` is set but `--proxied-server` was not passed, init aborts before creating the repository. The proxied-server flags configure a managed dolt sql-server behind a proxy; without `--proxied-server` they have no meaning, so the CLI rejects them eagerly instead of silently ignoring them.

Source

Thrown at cmd/bd/init.go:471

			}
			if err := validateProxiedServerConfig(serverConfigPath); err != nil {
				return fmt.Errorf("--proxied-server-config-path %v", err)
			}
		}
		if serverLogPath != "" {
			if !initProxiedServer {
				return fmt.Errorf("--proxied-server-log-path requires --proxied-server")
			}
			if !filepath.IsAbs(serverLogPath) {
				return fmt.Errorf("--proxied-server-log-path must be an absolute path, got %q", serverLogPath)
			}
			if err := validateProxiedServerLogPath(serverLogPath); err != nil {
				return fmt.Errorf("--proxied-server-log-path %v", err)
			}
		}
		if serverRootPath != "" {
			if !initProxiedServer {
				return fmt.Errorf("--proxied-server-root-path requires --proxied-server")
			}
			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 {

View on GitHub (pinned to 71377f2769)

Solutions

  1. Add `--proxied-server` to the `bd init` command line.
  2. Set the environment variable BEADS_DOLT_PROXIED_SERVER=1, which makes initProxiedServer true (cmd/bd/init.go:424-426).
  3. Remove `--proxied-server-root-path` if you did not intend to set up a proxied server.

Example fix

// before
bd init --proxied-server-root-path /var/lib/beads/dolt
// after
bd init --proxied-server --proxied-server-root-path /var/lib/beads/dolt
Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
if [[ -n "$ROOT_PATH" ]] && [[ -z "$PROXIED" ]]; then
  echo "--proxied-server-root-path requires --proxied-server" >&2; exit 2
fi
bd init ${PROXIED:+--proxied-server} ${ROOT_PATH:+--proxied-server-root-path "$ROOT_PATH"}

Type guard

func proxiedFlagsValid(useProxied, hasRootPath bool) bool { return !hasRootPath || useProxied }

Try / catch

if out, err := exec.Command("bd", "init", args...).CombinedOutput(); err != nil {
    if strings.Contains(string(out), "requires --proxied-server") {
        // add --proxied-server and retry
    }
}

Prevention

When it happens

Trigger: Running `bd init --proxied-server-root-path /some/path` (or with BEADS_DOLT_PROXIED_SERVER unset) without the `--proxied-server` flag. Exact check: `serverRootPath != "" && !initProxiedServer` at cmd/bd/init.go:469-472.

Common situations: Copy-pasting a proxied-server init command from docs or a teammate and dropping the `--proxied-server` flag; scripts that append root-path flags conditionally; environments where the BEADS_DOLT_PROXIED_SERVER=1 env var (which implies --proxied-server) was removed while flag arguments remained.

Related errors

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