gastownhall/beads · error

uow: creating server root directory: %w

Error message

uow: creating server root directory: %w

What it means

After resolving the server root path, the provider ensures the directory tree exists via os.MkdirAll with config.BeadsDirPerm. This error wraps an MkdirAll failure, meaning the provider could not create (or could not write to) the directory where the external Dolt server's data and files live. It is a filesystem permission or environment problem, not a logic error.

Source

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

		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,
		LogFilePath: serverLogFilePath,
		External:    external,
		IdleTimeout: idleTimeout,
		Port:        proxyPort,
	})
	if err != nil {
		return nil, fmt.Errorf("uow: get proxy endpoint: %w", err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check permissions on the parent directories of serverRootDir and ensure the process user can create it (chown/chmod or pick a writable location)
2. Verify no regular file exists at serverRootDir or one of its ancestors (MkdirAll fails with ENOTDIR)
3. Inspect the wrapped cause after "uow: creating server root directory: " to identify the exact OS error (EACCES, ENOTDIR, EROFS, ENOSPC)
4. If running in a container, mount the data directory as a writable volume

Example fix

// before (container, read-only path)
-u BD_SERVER_ROOT=/data
// after
-v bd-data:/data (writable volume) and ensure ownership matches the process user: chown 1000:1000 /var/lib/bd-data

if err := os.MkdirAll(serverRootDir, config.BeadsDirPerm); err != nil {
    return fmt.Errorf("pre-check: cannot create server root dir %q: %w", serverRootDir, err)
}

func writableDir(path string) bool {
    if fi, err := os.Stat(path); err == nil {
        return fi.IsDir() && unix.Access(path, unix.W_OK) == nil
    }
    parent := filepath.Dir(path)
    return unix.Access(parent, unix.W_OK) == nil
}

provider, err := uow.NewExternalDoltServerUOWProvider(ctx, db, root, dir, ext)
if err != nil {
    if strings.Contains(err.Error(), "creating server root directory") {
        var pe *fs.PathError
        if errors.As(err, &pe) {
            return fmt.Errorf("filesystem: cannot create %s (%v); check permissions/ownership", pe.Path, pe.Err)
        }
    }
    return err
}

When it happens

Trigger: os.MkdirAll(absServerRootDir, config.BeadsDirPerm) fails: parent path is a file, permission denied on an ancestor directory, read-only filesystem, or disk/quota issues.

Common situations: serverRootDir points inside a read-only container filesystem or a root-owned directory the process user cannot write; a file exists at the target path; a mounted volume with wrong ownership (common in Docker/K8s deployments).

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• uow: resolving server root dir: %w
• dolt path is not executable
• creating .bd-dolt-ok marker: %w
• failed to remove Dolt database: %w
• inspecting remote target %s: %w

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