gastownhall/beads · error

uow: external: %w

Error message

uow: external: %w

What it means

This is a wrapped error: the external Dolt server connection descriptor (host, port, credentials, etc.) failed its own Validate() check and the provider re-wraps it as "uow: external: <reason>". The provider defers detailed validation to the ExternalDoltServer type and surfaces its message so callers get a single consolidated error. The real cause is always in the wrapped message after the prefix.

Source

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

	rootUser string,
	rootPassword string,
	proxyPort int,
	idleTimeout time.Duration,
	teamServer bool,
	expectedProjectID string,
	opts ...ProviderOption,
) (UnitOfWorkProvider, error) {
	if idleTimeout == 0 {
		idleTimeout = defaultProxyIdleTimeout
	}
	if database == "" {
		return nil, fmt.Errorf("uow: database name must not be empty (caller should default to %q)", "beads")
	}
	if rootUser == "" {
		return nil, fmt.Errorf("uow: rootUser must not be empty")
	}
	if err := external.Validate(); err != nil {
		return nil, fmt.Errorf("uow: external: %w", err)
	}

	absServerRootDir, err := filepath.Abs(serverRootDir)
	if err != nil {
		return nil, fmt.Errorf("uow: resolving server root dir: %w", err)
	}

	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,

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause after "uow: external: " to see which field Validate() rejected
2. Fix the offending field in the ExternalDoltServer config (host, port, user, password)
3. Run the ExternalDoltServer's Validate() yourself before calling the provider to get the error earlier and un-wrapped

if err := external.Validate(); err != nil {
    return fmt.Errorf("invalid external dolt server config: %w", err)
}
// only then call NewExternalDoltServerUOWProvider

provider, err := uow.NewExternalDoltServerUOWProvider(ctx, db, root, dir, ext)
if err != nil {
    var cause error
    if errors.Unwrap(err) != nil && strings.HasPrefix(err.Error(), "uow: external: ") {
        errors.As(err, &cause) // inspect wrapped Validate() failure
        return fmt.Errorf("external dolt server config invalid: %w", cause)
    }
    return err
}

When it happens

Trigger: Calling NewExternalDoltServerUOWProvider with an ExternalDoltServer config that fails Validate() — e.g. empty host, invalid/missing port, missing password for the app user, or malformed address.

Common situations: Hand-edited config pointing at the external Dolt server (typo in host, port 0, empty password); secrets not injected in a container/CI environment so credential fields are empty; struct built programmatically with fields partially set.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• uow: database name must not be empty (caller should default
• uow: rootUser must not be empty
• ExternalDoltConfig: Port %d out of range [1, 65535]
• database name cannot be empty
• uow: doltBinExec must not be empty

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