gastownhall/beads · error

uow: backend: %w

Error message

uow: backend: %w

What it means

The proxy.Backend value passed to NewDoltServerUOWProvider failed its own Validate() check. The backend describes which Dolt server backend mode to use (e.g. how the server is launched); an invalid or zero-value backend cannot be used to build the proxy endpoint. The underlying Validate error is wrapped for detail.

Source

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

	serverConfigFilePath string,
	backend proxy.Backend,
	rootUser string,
	rootPassword string,
	doltBinExec 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 err := backend.Validate(); err != nil {
		return nil, fmt.Errorf("uow: backend: %w", err)
	}
	if rootUser == "" {
		return nil, fmt.Errorf("uow: rootUser must not be empty")
	}
	if doltBinExec == "" {
		return nil, fmt.Errorf("uow: doltBinExec must not be empty")
	}

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

	if err := os.MkdirAll(absServerRootDir, config.BeadsDirPerm); err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect the wrapped message after 'uow: backend:' for the exact validation failure
2. Use a recognized backend constant/constructor from the proxy package instead of a raw literal
3. Fix the config source so it emits a supported backend name
4. Upgrade/downgrade consistently so backend enum values match the library version

Example fix

// before
backend := proxy.Backend{} // zero value, fails Validate
// after
backend, err := proxy.BackendFromString("embedded")
if err != nil { return err }

func validateBackend(b proxy.Backend) error {
    if err := b.Validate(); err != nil {
        return fmt.Errorf("backend invalid before provider call: %w", err)
    }
    return nil
}

func backendIsValid(b proxy.Backend) bool { return b.Validate() == nil }

if err := backend.Validate(); err != nil { return fmt.Errorf("config: %w", err) }
prov, err := NewDoltServerUOWProvider(...)
if err != nil && strings.Contains(err.Error(), "uow: backend:") {
    return fmt.Errorf("unsupported backend: %w", err)
}

When it happens

Trigger: Calling NewDoltServerUOWProvider with a zero-value proxy.Backend, a backend constructed from an unsupported string/enum, or a Backend whose Validate() rejects the combination of fields.

Common situations: Config parsing produced an unknown backend name; a struct literal Backend{} was passed without setting the kind; switching backend types after a version change left the old value invalid.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• backend must be set
• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required
• ErrPrefixMismatch

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