newProxiedServerUOWProvider: proxied server root (from env o

Error message

newProxiedServerUOWProvider: proxied server root (from env or %s): %w

What it means

In the managed proxied server path, after resolving the root, bd validates it with validateProxiedServerRootPath and wraps failures with this error. Validation passes only when the path does not exist yet, or exists as a directory; it fails when the root exists but is not a directory (regular file, symlink-to-file, socket) or when os.Stat returns a non-NotExist error (e.g. permission denied on a parent). The message mentions proxied_server_client_info.json because that sidecar commonly supplies the root path.

Source

Thrown at cmd/bd/uow_factory.go:493

	// precedence (env > sidecar > PATH) and probe hardening (timeout,
	// output cap, pre-exec validation).
	//
	// The error label names this function rather than the proxied-server
	// entry point: since upstream's server-mode path (bd serve ->
	// newSQLServerUOWProvider) also lands here, a hardcoded
	// "newProxiedServerUOWProvider" would mislabel a `bd serve` failure as a
	// proxied-server one.
	doltBin, err := resolveAndProbeDolt(ctx, "newManagedProxiedServerUOWProvider", quietFlag)
	if err != nil {
		return nil, err
	}

	rootPath, err := resolveProxiedServerRootPath(beadsDir)
	if err != nil {
		return nil, fmt.Errorf("newProxiedServerUOWProvider: resolve root path: %w", err)
	}
	if err := validateProxiedServerRootPath(rootPath); err != nil {
		return nil, fmt.Errorf("newProxiedServerUOWProvider: proxied server root (from env or %s): %w", configfile.ProxiedServerClientInfoFileName, err)
	}

	configPath, err := ensureProxiedServerConfig(beadsDir)
	if err != nil {
		return nil, err
	}

	logPath, isCustomLog, err := resolveProxiedServerLogPath(beadsDir)
	if err != nil {
		return nil, fmt.Errorf("newProxiedServerUOWProvider: resolve log path: %w", err)
	}
	if isCustomLog {
		if err := validateProxiedServerLogPath(logPath); err != nil {
			return nil, fmt.Errorf("newProxiedServerUOWProvider: proxied server log (from env or %s): %w", configfile.ProxiedServerClientInfoFileName, err)
		}
	}

	return uow.NewDoltServerUOWProvider(

View on GitHub (pinned to 71377f2769)

Solutions

ls -la the resolved root path; if it is a file, remove or move it so the directory can exist
Correct BEADS_PROXIED_SERVER_ROOT_PATH or the sidecar's root_path to a real (or creatable) directory
Restore traversal permissions on parent directories (chmod +x on each ancestor for the running user)
Delete the stale sidecar to fall back to the default Dolt data dir

Example fix

// before: sidecar root_path points at a file
{"root_path": "/var/lib/beads/old-server.tar"}
// after
{"root_path": "/var/lib/beads/shared-server/dolt"}

Defensive patterns

Strategy: validation

Validate before calling

root := os.Getenv("BEADS_PROXIED_SERVER_ROOT_PATH")
if root == "" {
	root = "<path from sidecar>"
}
if fi, err := os.Stat(root); err == nil && !fi.IsDir() {
	return fmt.Errorf("root %s exists and is not a directory", root)
} else if err != nil && !os.IsNotExist(err) {
	return fmt.Errorf("cannot stat root %s: %v", root, err)
}

Type guard

func usableRoot(path string) bool {
	fi, err := os.Stat(path)
	return err == nil && fi.IsDir() || os.IsNotExist(err)
}

Prevention

Confirm the resolved root is a directory after restores, copies, or machine migrations
Delete stale sidecars when moving workspaces between machines
Keep ancestor directories (home, .beads) traversable (o+x) for the runtime user
Use bd migrate-dolt-mode for all root relocation instead of manual edits

When it happens

Trigger: Sidecar root_path or BEADS_PROXIED_SERVER_ROOT_PATH points at an existing non-directory; stat fails with EACCES/EBUSY etc. on the path or a parent.

Common situations: A file was placed where the shared-server Dolt root should live; stale sidecar from a previous machine layout; backup restore replaced the directory with a file; permission changes on ~/.beads.

Related errors

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