gastownhall/beads · error

cannot determine home directory: %w

Error message

cannot determine home directory: %w

What it means

SharedServerPath computes the default shared-server state directory under the user's home (~/.beads/shared-server). If os.UserHomeDir fails (no HOME set, or the OS call errors), the path cannot be determined and this error wraps the cause. BEADS_SHARED_SERVER_DIR overrides the home-derived path entirely.

Source

Thrown at internal/doltserver/doltserver.go:254

	if err != nil || secs < 1 {
		fmt.Fprintf(os.Stderr,
			"Warning: BEADS_DOLT_READY_TIMEOUT=%q is not a positive integer; using default %s\n",
			v, defaultTimeout)
		return defaultTimeout
	}
	return time.Duration(secs) * time.Second
}

// SharedServerPath returns the directory for shared server state files without
// creating it. Override with BEADS_SHARED_SERVER_DIR for testing or custom
// layouts; otherwise it resolves to ~/.beads/shared-server/.
func SharedServerPath() (string, error) {
	if d := os.Getenv("BEADS_SHARED_SERVER_DIR"); d != "" {
		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
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Set the BEADS_SHARED_SERVER_DIR environment variable to an explicit writable directory.
2. Set HOME (and USERPROFILE on Windows) in the service/container environment.
3. Fix the wrapped %w cause — e.g. point the user's home at an existing directory.
4. Run the command as a user whose home directory exists and is readable.

Example fix

// before
# systemd unit without HOME
ExecStart=/usr/local/bin/bd dolt start
// after
[Service]
Environment=HOME=/home/bd
ExecStart=/usr/local/bin/bd dolt start

if os.Getenv("BEADS_SHARED_SERVER_DIR") == "" {
    if _, err := os.UserHomeDir(); err != nil {
        os.Setenv("BEADS_SHARED_SERVER_DIR", "/var/lib/beads/shared-server") // explicit fallback
    }
}

When it happens

Trigger: Calling SharedServerPath (directly or via SharedServerDir/SharedDoltPath) with no BEADS_SHARED_SERVER_DIR set while HOME is unset/empty or unreadable — common in stripped-down service, cron, or container environments.

Common situations: Running bd from systemd/cron with a minimal env (no HOME); Docker containers running as a non-root user without HOME; Windows profile-location API failures; CI runners with sanitized environments.

Related errors

• unable to determine home directory: %w
• %s: %w
• bd binary not found in PATH: %w
• not a git repository
• resolve path: %w

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