gastownhall/beads · error

uow: creating server root directory: %w

Error message

uow: creating server root directory: %w

What it means

os.MkdirAll failed to create (or confirm) the server root directory at the absolutized path, using config.BeadsDirPerm permissions. This typically means a permissions problem on a parent directory, the path exists as a file, or the filesystem is read-only. The OS error is wrapped for detail.

Source

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

	}
	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 {
		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 OS error (mkdir ...: permission denied / not a directory / no space) to pinpoint the cause
2. Ensure the parent directory exists and is writable by the process user
3. Remove or rename any regular file occupying the server root path
4. Point serverRootDir at a writable location (e.g. $BEADS_DIR or /var/lib) and check disk space/mount flags

Example fix

// before
prov, err := NewDoltServerUOWProvider(ctx, os.TempDir()+"/beads/locked", ...) // read-only mount
// after
rootDir := filepath.Join(os.Getenv("HOME"), ".beads", "dolt")
if err := os.MkdirAll(filepath.Dir(rootDir), 0o755); err != nil { return err }
prov, err := NewDoltServerUOWProvider(ctx, rootDir, ...)

if err := os.MkdirAll(serverRootDir, 0o755); err != nil {
    return fmt.Errorf("server root not creatable before provider init: %w", err)
}
// pre-creating surfaces permission/path issues with a clearer failure point

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

prov, err := NewDoltServerUOWProvider(...)
if err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) && strings.Contains(err.Error(), "creating server root directory") {
        return fmt.Errorf("check permissions/ownership on %s: %w", pe.Path, err)
    }
    return err
}

When it happens

Trigger: NewDoltServerUOWProvider called with absServerRootDir that cannot be created: parent dir not writable, a file already occupies the path, disk full, or read-only mount.

Common situations: Server root under $HOME when HOME is wrong/unwritable (daemons, cron, containers); ~/.beads/beads-data accidentally replaced by a regular file; read-only container filesystem; full disk.

Related errors

• refusing to chmod %s: path is not a directory
• failed to create user config directory: %w
• dolt path is not executable
• failed to create backup directory: %w
• failed to create temp file: %w

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