gastownhall/beads · error

cannot create shared server directory %s: %w

Error message

cannot create shared server directory %s: %w

What it means

SharedServerDir lazily creates the shared dolt server directory (typically ~/.beads/shared-server/) used in shared-server mode. It wraps os.MkdirAll with config.BeadsDirPerm; if the OS refuses to create the directory, the path and underlying OS error are wrapped into this error. It is thrown by the library because the shared server cannot start without its state directory on disk.

Source

Thrown at internal/doltserver/doltserver.go:268

		return d, nil
	}
	home, err := os.UserHomeDir()
	if err != nil {
		return "", fmt.Errorf("cannot determine home directory: %w", err)
	}
	return filepath.Join(home, ".beads", "shared-server"), nil
}

// SharedServerDir returns the directory for shared server state files.
// Returns ~/.beads/shared-server/ (created on first use).
// Override with BEADS_SHARED_SERVER_DIR env var for testing or custom layouts.
func SharedServerDir() (string, error) {
	dir, err := SharedServerPath()
	if err != nil {
		return "", err
	}
	if err := os.MkdirAll(dir, config.BeadsDirPerm); err != nil {
		return "", fmt.Errorf("cannot create shared server directory %s: %w", dir, err)
	}
	return dir, nil
}

// SharedDoltDir returns the dolt data directory for the shared server.
// Returns ~/.beads/shared-server/dolt/ (created on first use).
func SharedDoltDir() (string, error) {
	serverDir, err := SharedServerDir()
	if err != nil {
		return "", err
	}
	dir := filepath.Join(serverDir, "dolt")
	if err := os.MkdirAll(dir, config.BeadsDirPerm); err != nil {
		return "", fmt.Errorf("cannot create shared dolt directory %s: %w", dir, err)
	}
	return dir, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped OS error in the message for the root cause (EACCES, ENOSPC, ENOTDIR, etc.)
2. Verify $HOME is set and writable: touch $HOME/.beads/test
3. If a plain file exists at ~/.beads/shared-server, remove or rename it
4. Fix permissions: chown/chmod the ~/.beads tree, or mount a writable volume
5. Free disk space or remount the filesystem read-write

Example fix

// before: blindly calling and panicking on error
dir, _ := doltserver.SharedServerDir()
// after: handle the wrapped OS error
dir, err := doltserver.SharedServerDir()
if err != nil {
    return fmt.Errorf("shared server unavailable: %w", err)
}

// Pre-check before calling SharedServerDir
home := os.Getenv("HOME")
if home == "" {
    return fmt.Errorf("HOME is not set; cannot locate shared server dir")
}
if fi, err := os.Stat(filepath.Join(home, ".beads")); err == nil && !fi.IsDir() {
    return fmt.Errorf("~/.beads is a file, not a directory")
}

func isSharedDirErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "cannot create shared server directory")
}

dir, err := doltserver.SharedServerDir()
if err != nil {
    if strings.Contains(err.Error(), "permission denied") {
        // fall back to a writable BEADS_DIR or abort with guidance
    }
    return err
}

When it happens

Trigger: Calling SharedServerDir() (directly or via SharedDoltDir/resolveServerDir/DefaultConfig) when os.MkdirAll on the shared server path fails — e.g. HOME is unset or unwritable, ~/.beads is owned by another user, a file exists at the directory path, or the disk is full/readonly.

Common situations: Running bd under a service account with no writable HOME, HOME pointing to a read-only NFS mount, a stray file named shared-server inside ~/.beads, or container images with a read-only root filesystem and no volume for ~/.beads.

Related errors

• cannot create shared dolt directory %s: %w
• failed to create planning repo: %w
• ensureProxiedServerConfig: mkdir %s: %w
• create beads dir: %w
• fs: CreateBeadsDir: mkdir %s: %w

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