mislav/hub · error

Please set $BROWSER to a web launcher

Error message

Please set $BROWSER to a web launcher

What it means

hub's BrowserLauncher resolves which command opens a web page: it uses the BROWSER env var (after env expansion) or falls back to searchBrowserLauncher for the OS. If the resolved browser string is empty (BROWSER unset/empty and no OS default found), it returns this error and the caller (printBrowseOrCopy) falls back to copying the URL instead.

Source

Thrown at utils/utils.go:39

		ui.Errorln(err)
		os.Exit(1)
	}
}

func ConcatPaths(paths ...string) string {
	return strings.Join(paths, "/")
}

func BrowserLauncher() ([]string, error) {
	browser := os.Getenv("BROWSER")
	if browser == "" {
		browser = searchBrowserLauncher(runtime.GOOS)
	} else {
		browser = os.ExpandEnv(browser)
	}

	if browser == "" {
		return nil, errors.New("Please set $BROWSER to a web launcher")
	}

	return shellquote.Split(browser)
}

func searchBrowserLauncher(goos string) (browser string) {
	switch goos {
	case "darwin":
		browser = "open"
	case "windows":
		browser = "cmd /c start"
	default:
		candidates := []string{"xdg-open", "cygstart", "x-www-browser", "firefox",
			"opera", "mozilla", "netscape"}
		for _, b := range candidates {
			path, err := exec.LookPath(b)
			if err == nil {
				browser = path

View on GitHub (pinned to 5c547ed804)

Solutions

1. Set the BROWSER environment variable to a launcher command, e.g. `export BROWSER=open` (macOS), `xdg-open` (Linux), or a full browser path.
2. Use a full path if the browser isn't on PATH: export BROWSER="/usr/bin/firefox".
3. Rely on the fallback: hub copies the URL to the clipboard when this error occurs, so paste it into a browser manually.

Example fix

// before
$ hub browse
Please set $BROWSER to a web launcher
// after
$ export BROWSER=xdg-open
$ hub browse

if [ -z "$BROWSER" ] && ! command -v xdg-open >/dev/null 2>&1; then
  export BROWSER=xdg-open   # or 'open' on macOS
fi

// hub itself falls back to copying the URL; in scripts:
if hub browse 2>&1 | grep -q 'BROWSER'; then
  echo "URL copied to clipboard; open manually"
fi

When it happens

Trigger: Calling anything that opens a browser (`hub browse`) on an OS where searchBrowserLauncher finds nothing (e.g. an unsupported/uncommon OS) while $BROWSER is unset or empty after expansion.

Common situations: Running hub inside a container/SSH session without a desktop environment; using an exotic OS where hub has no built-in launcher detection; BROWSER set to empty string; BROWSER containing only whitespace after expansion.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Can't load git var: GIT_EDITOR
• Error: couldn't detect shell type. Please specify your shell
• hub alias: unsupported shell supported shells: %s
• 'create' must be run from inside a git repository
• error running git version: %s

AI-assisted analysis of mislav/hub@5c547ed804 (2026-09-01). Data as JSON: /api/errors/86bf097fe767f29c. Report an issue: GitHub.