{"record":{"id":"4d9292326f169422","repo":"MHSanaei/3x-ui","slug":"xray-update-aborted-the-downloaded-archive-does-n","errorCode":null,"errorMessage":"Xray update aborted: the downloaded archive does not match the official SHA-256 checksum, so the image is corrupted or differs from the official release. Please exit and re-download the official image, then try again (expected %s, got %s)","messagePattern":"Xray update aborted: the downloaded archive does not match the official SHA-256 checksum, so the image is corrupted or differs from the official release\\. Please exit and re-download the official image, then try again \\(expected (.+?), got (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/web/service/server.go","lineNumber":941,"sourceCode":"\t// sidecar before installing it. TLS protects the transport, not the artifact;\n\t// a corrupted or tampered asset must not be installed and run as xray.\n\twant, err := s.fetchXrayDigestSHA256(client, url+\".dgst\")\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tif _, err := file.Seek(0, io.SeekStart); err != nil {\n\t\treturn \"\", err\n\t}\n\thasher := sha256.New()\n\tif _, err := io.Copy(hasher, file); err != nil {\n\t\treturn \"\", err\n\t}\n\tif got := hex.EncodeToString(hasher.Sum(nil)); !strings.EqualFold(got, want) {\n\t\t// User-facing warning: the archive's SHA-256 does not match the official\n\t\t// release checksum, so the download is corrupted or has been tampered\n\t\t// with. Abort the install so a bad binary is never run, and tell the user\n\t\t// to retry/re-download rather than proceed with a mismatched image.\n\t\treturn \"\", fmt.Errorf(\"Xray update aborted: the downloaded archive does not match the official SHA-256 checksum, so the image is corrupted or differs from the official release. Please exit and re-download the official image, then try again (expected %s, got %s)\", want, got)\n\t}\n\n\tok = true\n\treturn path, nil\n}\n\n// fetchXrayDigestSHA256 downloads the .dgst sidecar XTLS publishes next to each\n// release asset and returns the SHA2-256 hex digest it lists.\nfunc (s *ServerService) fetchXrayDigestSHA256(client *http.Client, dgstURL string) (string, error) {\n\treq, reqErr := http.NewRequestWithContext(context.Background(), http.MethodGet, dgstURL, nil)\n\tif reqErr != nil {\n\t\treturn \"\", fmt.Errorf(\"download xray checksum: %w\", reqErr)\n\t}\n\tresp, err := client.Do(req)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"download xray checksum: %w\", err)\n\t}\n\tdefer resp.Body.Close()","sourceCodeStart":923,"sourceCodeEnd":959,"githubUrl":"https://github.com/MHSanaei/3x-ui/blob/ad32144c42455696ea9f14e12168beac3e25f5d2/internal/web/service/server.go#L923-L959","documentation":"Returned by downloadXRay when the SHA-256 of the downloaded zip does not match the digest published in XTLS's .dgst sidecar. This is an integrity gate: TLS protects the transport, not the artifact, so a mismatch means the download is corrupted or tampered with, and the install is aborted so the binary is never run. Expected (from .dgst) and got (computed) digests are both included for comparison.","triggerScenarios":"Truncated/corrupted download through a flaky proxy; a compromised or misbehaving mirror/CDN node altering the zip; disk corruption of the temp file; an out-of-sync .dgst fetched for a different asset version than the zip actually served.","commonSituations":"Updating Xray through an intercepting TLS-terminating proxy; CDN edge inconsistency where zip and .dgst come from different release revisions; packet-level corruption on long transfers.","solutions":["Retry the update — transient corruption is the most common cause","Compare the two digests shown in the message against the release's official .dgst to distinguish corruption from tampering","Disable any TLS-intercepting proxy and retry from a clean network path","If tampering is suspected, download the zip manually from github.com/XTLS/Xray-core/releases and verify with sha256sum before trusting the host"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Independent verification before trusting the host\n// sha256sum Xray-linux-64.zip  → compare with the SHA2-256 line in the release's .dgst\nwanted := \"<hex from https://github.com/XTLS/Xray-core/releases/download/<ver>/<file>.dgst>\"\ngot := sha256sumFile(zipPath)\nif !strings.EqualFold(wanted, got) { /* do not install */ }\n","typeGuard":null,"tryCatchPattern":"err := s.UpdateXray(version)\nif err != nil && strings.Contains(err.Error(), \"does not match the official SHA-256\") {\n    // never bypass: retry from a clean network, then manual verification; treat persistent mismatch as compromise\n    return err\n}\n","preventionTips":["Never bypass or downgrade a checksum mismatch to a warning","Retry once for transient corruption; a second mismatch means investigate the network path","Avoid TLS-intercepting proxies for binary downloads","Keep expected/got digests in the error so operators can cross-check upstream"],"tags":["xray-update","integrity","checksum","security"],"backgroundTag":null,"analyzedSha":"ad32144c42455696ea9f14e12168beac3e25f5d2","analyzedAt":"2026-08-15T11:13:23.905Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}