{"record":{"id":"d39ac8020b6a04d7","repo":"MHSanaei/3x-ui","slug":"panel-web-update-is-supported-only-on-linux-instal","errorCode":null,"errorMessage":"panel web update is supported only on Linux installations","messagePattern":"panel web update is supported only on Linux installations","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/web/service/panel/panel.go","lineNumber":228,"sourceCode":"\t\tstatus.State = updateStatePending\n\t}\n\treturn &status\n}\n\nfunc (s *PanelService) startUpdate(useDev bool) (int64, error) {\n\trunID := time.Now().UnixNano()\n\tif !acquireUpdateSlot(runID) {\n\t\treturn 0, fmt.Errorf(\"a panel update is already in progress\")\n\t}\n\tlaunched := false\n\tdefer func() {\n\t\tif !launched {\n\t\t\treleaseUpdateSlot()\n\t\t}\n\t}()\n\n\tif runtime.GOOS != \"linux\" {\n\t\treturn 0, fmt.Errorf(\"panel web update is supported only on Linux installations\")\n\t}\n\n\tbash, err := exec.LookPath(\"bash\")\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"bash is required to run the panel updater: %w\", err)\n\t}\n\n\tscriptPath, err := downloadPanelUpdater()\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\n\tstatusFile := config.GetUpdateStatusFilePath()\n\n\tmainFolder, serviceFolder := resolveUpdateFolders()\n\tupdateTag := \"\"\n\tif useDev {\n\t\tupdateTag = devReleaseTag","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/MHSanaei/3x-ui/blob/ad32144c42455696ea9f14e12168beac3e25f5d2/internal/web/service/panel/panel.go#L210-L246","documentation":"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.","triggerScenarios":"Invoking the panel update API on a Windows or macOS build of 3x-ui.","commonSituations":"Running the panel binary on a desktop OS for testing and clicking update; a FreeBSD jail deployment.","solutions":["Update manually on non-Linux: stop the panel, replace the binary, restart","Deploy on Linux (the supported platform) to use the web updater"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if runtime.GOOS != \"linux\" {\n    // hide web-update UI / return 'manual update only' before calling StartUpdate\n}","typeGuard":null,"tryCatchPattern":"_, err := panelService.StartUpdate(false)\nif err != nil && strings.Contains(err.Error(), \"supported only on Linux\") {\n    // fall back to documented manual update procedure\n}","preventionTips":["Gate the update UI on the reported OS","Use Linux hosts when the web updater is a requirement"],"tags":["platform","updates","panel-update","linux"],"backgroundTag":null,"analyzedSha":"ad32144c42455696ea9f14e12168beac3e25f5d2","analyzedAt":"2026-08-15T11:13:23.905Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}