MHSanaei/3x-ui · warning

panel web update is supported only on Linux installations

Error message

panel web update is supported only on Linux installations

What it means

The web-based self-update is implemented as a bash + systemd-run script and is explicitly gated to runtime.GOOS == "linux". On any other OS (windows, darwin, freebsd builds of the panel) startUpdate refuses immediately after acquiring the slot. This is a deliberate platform restriction of the updater script, not a bug.

Source

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

		status.State = updateStatePending
	}
	return &status
}

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

View on GitHub (pinned to ad32144c42)

Solutions

1. Update manually on non-Linux: stop the panel, replace the binary, restart
2. Deploy on Linux (the supported platform) to use the web updater

if runtime.GOOS != "linux" {
    // hide web-update UI / return 'manual update only' before calling StartUpdate
}

_, err := panelService.StartUpdate(false)
if err != nil && strings.Contains(err.Error(), "supported only on Linux") {
    // fall back to documented manual update procedure
}

When it happens

Trigger: Invoking the panel update API on a Windows or macOS build of 3x-ui.

Common situations: Running the panel binary on a desktop OS for testing and clicking update; a FreeBSD jail deployment.

Related errors

• failed to start panel update job: %w: %s
• failed to start panel update job: %w
• a panel update is already in progress
• bash is required to run the panel updater: %w
• download panel updater: %w

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