gastownhall/beads · error

uow: get proxy endpoint: %w

Error message

uow: get proxy endpoint: %w

What it means

proxy.GetCreateDatabaseProxyServerEndpoint failed while resolving or starting the Dolt database proxy server endpoint (it may launch/supervise a dolt server and pick host/port). Any failure inside — server spawn failure, bad config file, port conflicts, startup timeout — is wrapped here. At this point arguments have passed validation and the root directory exists.

Source

Thrown at internal/storage/uow/doltserver_provider.go:71

	if err != nil {
		return nil, fmt.Errorf("uow: resolving dolt bin exec: %w", err)
	}

	if err := os.MkdirAll(absServerRootDir, config.BeadsDirPerm); err != nil {
		return nil, fmt.Errorf("uow: creating server root directory: %w", err)
	}

	ep, err := proxy.GetCreateDatabaseProxyServerEndpoint(absServerRootDir, proxy.OpenOpts{
		Backend:        backend,
		ConfigFilePath: serverConfigFilePath,
		LogFilePath:    serverLogFilePath,
		DoltBinPath:    absDoltBinExec,
		Database:       database,
		IdleTimeout:    idleTimeout,
		Port:           proxyPort,
	})
	if err != nil {
		return nil, fmt.Errorf("uow: get proxy endpoint: %w", err)
	}

	return openAndInitSchema(ctx, ep, database, rootUser, rootPassword, "", teamServer, expectedProjectID, applyProviderOptions(opts))
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause after 'uow: get proxy endpoint:' for the concrete failure
2. Check the server log file (serverLogFilePath) for dolt server startup errors
3. Free the requested proxyPort or pass 0 to let the proxy choose one
4. Kill stale dolt server processes bound to the data dir (check for stale pid/socket files in serverRootDir)
5. Validate serverConfigFilePath contents and ensure doltBinExec is a compatible dolt version

Example fix

// before
prov, err := NewDoltServerUOWProvider(..., 3306, ...) // port in use
// after
prov, err := NewDoltServerUOWProvider(..., 0, ...) // ephemeral port
if err != nil {
    log.Fatalf("proxy endpoint: %v — see %s for server logs", err, serverLogFilePath)
}

// Pre-flight: port availability and writable log/config paths
if ln, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", proxyPort)); err != nil {
    return fmt.Errorf("proxy port %d in use", proxyPort)
} else { ln.Close() }
for _, p := range []string{serverLogFilePath, serverConfigFilePath} {
    if dir := filepath.Dir(p); dir != "" {
        if err := os.MkdirAll(dir, 0o755); err != nil { return err }
    }
}

func isProxyEndpointError(err error) bool {
    return err != nil && strings.Contains(err.Error(), "uow: get proxy endpoint:")
}

prov, err := NewDoltServerUOWProvider(...)
if isProxyEndpointError(err) {
    // inspect server log, then retry with an ephemeral port
    log.Printf("proxy endpoint failed: %v; see %s", err, serverLogFilePath)
    prov, err = NewDoltServerUOWProvider(... /* proxyPort = 0 */ ...)
}
if err != nil { return err }

When it happens

Trigger: NewDoltServerUOWProvider called when the dolt server fails to start (bad dolt binary, invalid serverConfigFilePath), the requested proxyPort is already in use, the log/config file paths are unwritable, or endpoint discovery times out.

Common situations: Port 3306/5xx already bound by another MySQL/dolt instance; stale dolt server from a previous run holding the socket; corrupted server config YAML; dolt binary version incompatible with the data dir; container lacking process-spawn permissions.

Related errors

• ExternalDoltConfig: Port %d out of range [1, 65535]
• dolt sql-server exited before listener became ready
• failed to remove backup: %w
• no Dolt server port configured and no server running; run an
• server not reachable: %w

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