What causes "bash is required to run the panel updater: %w" in MHSanaei/3x-ui?

Install bash: apt install bash / apk add bash, then restart the panel

bash is required to run the panel updater: %w

Error message

bash is required to run the panel updater: %w

What it means

The updater is a shell script executed via bash -lc; exec.LookPath("bash") must find a bash binary on PATH before anything else runs. Failure means no bash in PATH — typically minimal containers (distroless/scratch, alpine without bash, only busybox sh) or a stripped-down server image.

Source

Thrown at internal/web/service/panel/panel.go:233

func (s *PanelService) startUpdate(useDev bool) (int64, error) {
	runID := time.Now().UnixNano()
	if !acquireUpdateSlot(runID) {
		return 0, fmt.Errorf("a panel update is already in progress")
	}
	launched := false
	defer func() {
		if !launched {
			releaseUpdateSlot()
		}
	}()

	if runtime.GOOS != "linux" {
		return 0, fmt.Errorf("panel web update is supported only on Linux installations")
	}

	bash, err := exec.LookPath("bash")
	if err != nil {
		return 0, fmt.Errorf("bash is required to run the panel updater: %w", err)
	}

	scriptPath, err := downloadPanelUpdater()
	if err != nil {
		return 0, err
	}

	statusFile := config.GetUpdateStatusFilePath()

	mainFolder, serviceFolder := resolveUpdateFolders()
	updateTag := ""
	if useDev {
		updateTag = devReleaseTag
	}
	updateScript := fmt.Sprintf("set -e; trap 'rm -f %s' EXIT; %s %s", shellQuote(scriptPath), shellQuote(bash), shellQuote(scriptPath))
	runIDEnv := "XUI_UPDATE_RUN_ID=" + strconv.FormatInt(runID, 10)
	statusFileEnv := "XUI_UPDATE_STATUS_FILE=" + statusFile

View on GitHub (pinned to ad32144c42)

Solutions

Install bash: apt install bash / apk add bash, then restart the panel
Fix the service unit's PATH so /bin or /usr/bin (where bash lives) is included
Or perform a manual binary update instead of the web updater

Example fix

# before (alpine image)
docker exec panel sh -c 'which bash'   # empty -> update fails

# after
docker exec -u root panel apk add bash
docker restart panel

Defensive patterns

Strategy: validation

Validate before calling

if _, err := exec.LookPath("bash"); err != nil {
    return errors.New("bash not found; install it or update manually")
}

Try / catch

_, err := panelService.StartUpdate(false)
if err != nil && strings.Contains(err.Error(), "bash is required") {
    // instruct admin to install bash in the container/host, then retry
}

Prevention

Include bash in custom panel container images
Pre-flight check for bash before exposing the update button

When it happens

Trigger: Triggering the web update inside a container image that ships no bash (sh/dash/ash only), or with a sanitized PATH for the panel service.

Common situations: Alpine-based custom panel image without 'apk add bash'; systemd service with RestrictEnvironment/empty PATH; distroless container.

Related errors

AI-assisted analysis of MHSanaei/3x-ui@ad32144c42 (2026-08-15). Data as JSON: /api/errors/5d93552674e82b53. Report an issue: GitHub.