What causes "uow: get proxy endpoint: %w" in gastownhall/beads?

Check what occupies proxyPort (lsof -i : ) and pick a free port or stop the conflicting process.

uow: get proxy endpoint: %w

Error message

uow: get proxy endpoint: %w

What it means

This wraps a failure from proxy.GetCreateDatabaseProxyServerEndpoint, which resolves or starts the local database-proxy server endpoint before the schema is opened. It means the proxy layer could not produce a usable address/endpoint for the external dolt server (startup, port, or local state problem), so the unit-of-work provider cannot be created.

Source

Thrown at internal/storage/uow/external_doltserver_provider.go:67

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

	tlsConfigName, err := registerExternalTLSConfig(external)
	if err != nil {
		return nil, fmt.Errorf("uow: external TLS: %w", err)
	}

	ep, err := proxy.GetCreateDatabaseProxyServerEndpoint(absServerRootDir, proxy.OpenOpts{
		Backend:     proxy.BackendExternal,
		LogFilePath: serverLogFilePath,
		External:    external,
		IdleTimeout: idleTimeout,
		Port:        proxyPort,
	})
	if err != nil {
		return nil, fmt.Errorf("uow: get proxy endpoint: %w", err)
	}

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

func registerExternalTLSConfig(external configfile.ExternalDoltConfig) (string, error) {
	if !external.TLSRequired {
		return "", nil
	}
	tc, err := external.TLSClientConfig()
	if err != nil {
		return "", err
	}
	name := "beads-external-" + server.ExternalDoltServerID(external)
	if err := mysql.RegisterTLSConfig(name, tc); err != nil {
		return "", fmt.Errorf("register TLS config: %w", err)
	}
	return name, nil

View on GitHub (pinned to 71377f2769)

Solutions

Check what occupies proxyPort (lsof -i :<port>) and pick a free port or stop the conflicting process.
Inspect the proxy/server log file (serverLogFilePath) for the underlying startup error.
Clear stale proxy state under the server root directory and retry.
Confirm the external dolt server host/port in the ExternalDoltConfig is reachable (nc/host:port) before constructing the provider.

Example fix

// before
provider, err := uow.NewExternalDoltServerUOWProvider(ctx, rootDir, "beads", logPath, ext, "root", pw, 3311, 0, false, "")
// after (port already in use)
listener, _ := net.Listen("tcp", ":0")
freePort := listener.Addr().(*net.TCPAddr).Port
listener.Close()
provider, err := uow.NewExternalDoltServerUOWProvider(ctx, rootDir, "beads", logPath, ext, "root", pw, freePort, 0, false, "")

Defensive patterns

Strategy: retry

Validate before calling

func portFree(port int) bool {
	ln, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port))
	if err != nil {
		return false
	}
	ln.Close()
	return true
}

Try / catch

var provider uow.UnitOfWorkProvider
err := backoff.Retry(func() error {
	p, err := uow.NewExternalDoltServerUOWProvider(ctx, root, db, logPath, ext, user, pw, port, 0, false, "")
	if err != nil {
		if strings.Contains(err.Error(), "uow: get proxy endpoint:") {
			return err // retryable: port contention / transient startup
		}
		return backoff.Permanent(err)
	}
	provider = p
	return nil
})

Prevention

Pick proxy ports explicitly and check occupancy at startup.
Clean stale proxy state in the server root dir after crashes.
Read serverLogFilePath when startup fails; it names the root cause.
In CI, avoid fixed ports and use ephemeral ones.

When it happens

Trigger: Calling NewExternalDoltServerUOWProvider when the proxy cannot start or resolve its endpoint in absServerRootDir: the chosen proxyPort is already bound or invalid, the external dolt server cannot be reached/launched via proxy.OpenOpts{Backend: proxy.BackendExternal}, or the proxy's local state files in the server root dir are corrupt/locked.

Common situations: Another bd or dolt process already holds proxyPort; stale proxy state left over from a crashed run in the server root directory; container/CI environments where binding localhost ports is restricted; the external dolt server hostname/port is wrong so the proxy backend fails.

Related errors

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