newExternalProxiedServerUOWProvider: resolve log path: %w

Error message

newExternalProxiedServerUOWProvider: resolve log path: %w

What it means

newExternalProxiedServerUOWProvider resolves the proxied server's log file path (env BEADS_PROXIED_SERVER_LOG, the proxied_server_client_info.json sidecar log_path, or <root>/server.log) and wraps any resolution failure with this error. Resolution fails when the sidecar cannot be loaded (corrupt JSON, unreadable file) since resolveProxiedServerLogPath consults it even when the env var is empty. It is distinct from the later validation error: this one fires before validation, during path lookup.

Source

Thrown at cmd/bd/uow_factory.go:441

// newExternalProxiedServerUOWProvider fronts a Dolt SQL server this process
// neither started nor owns. "Proxied" in the name is the PROXY it builds, not
// the workspace mode: since bd-emv a server-mode workspace lands here too, and
// the paths it resolves (root, log) are the same ones proxied mode uses because
// both modes root their server at the same directory.
func newExternalProxiedServerUOWProvider(ctx context.Context, beadsDir string, topology sqlServerUOWTopology, opts ...uow.ProviderOption) (p uow.UnitOfWorkProvider, err error) {
	defer func() { p, err = activateEventsJournalProvider(ctx, beadsDir, p, err) }()
	rootPath, err := resolveProxiedServerRootPath(beadsDir)
	if err != nil {
		return nil, fmt.Errorf("newExternalProxiedServerUOWProvider: resolve root path: %w", err)
	}
	if err := validateProxiedServerRootPath(rootPath); err != nil {
		return nil, fmt.Errorf("newExternalProxiedServerUOWProvider: proxied server root (from env or %s): %w", configfile.ProxiedServerClientInfoFileName, err)
	}

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

	if err := os.MkdirAll(rootPath, config.BeadsDirPerm); err != nil {
		return nil, fmt.Errorf("newExternalProxiedServerUOWProvider: mkdir %s: %w", rootPath, err)
	}

	return uow.NewExternalDoltServerUOWProvider(
		ctx,
		rootPath,
		topology.database,
		logPath,
		*topology.external,
		topology.external.ResolvedUser(),

View on GitHub (pinned to 71377f2769)

Solutions

Inspect .beads/proxied_server_client_info.json: fix invalid JSON or delete the sidecar so defaults are used
Set BEADS_PROXIED_SERVER_LOG explicitly so the sidecar is not needed for log resolution
Fix permissions on the sidecar file (and the .beads directory) for the user running bd
Re-run bd migrate-dolt-mode to regenerate the sidecar

Example fix

// before: corrupt sidecar
$ cat .beads/proxied_server_client_info.json
{"root_path": "/var/lib/beads",  // trailing junk
// after: remove or repair
rm .beads/proxied_server_client_info.json
# or export BEADS_PROXIED_SERVER_LOG=/var/log/bd/server.log

Defensive patterns

Strategy: validation

Validate before calling

sidecar := filepath.Join(beadsDir, ".beads", "proxied_server_client_info.json")
if _, err := os.Stat(sidecar); err == nil {
	var raw map[string]any
	b, _ := os.ReadFile(sidecar)
	if err := json.Unmarshal(b, &raw); err != nil {
		return fmt.Errorf("sidecar %s is corrupt: %v", sidecar, err)
	}
}

Try / catch

path, _, err := resolveProxiedServerLogPath(beadsDir)
if err != nil {
	var perr *fs.PathError
	if errors.As(err, &perr) && errors.Is(perr.Err, syscall.EACCES) {
		// fix permissions or set BEADS_PROXIED_SERVER_LOG and retry
	}
	return err
}

Prevention

Never hand-edit proxied_server_client_info.json; regenerate it with bd migrate-dolt-mode
Validate the sidecar JSON after any manual change (jq . proxied_server_client_info.json)
Keep .beads readable by the user (and group) running bd
Set BEADS_PROXIED_SERVER_LOG explicitly in managed environments to avoid sidecar dependence

When it happens

Trigger: proxied_server_client_info.json exists but is corrupt JSON, unreadable (bad permissions), or fails to parse, and resolveProxiedServerLogPath calls LoadProxiedServerClientInfo to read log_path.

Common situations: A crashed or interrupted migration left a truncated sidecar; the sidecar was edited by hand with invalid JSON; file permissions changed so bd running as another user cannot read .beads/proxied_server_client_info.json.

Related errors

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