MHSanaei/3x-ui · error

download xray checksum: unexpected HTTP %d

Error message

download xray checksum: unexpected HTTP %d

What it means

Returned by fetchXrayDigestSHA256 when the .dgst sidecar URL responds with a non-200 status. XTLS publishes a .dgst next to every release asset, so a 404 usually means the requested version is old enough to predate .dgst publishing, or the asset name is wrong; 429 is CDN rate limiting after the archive download consumed the budget.

Source

Thrown at internal/web/service/server.go:961

	ok = true
	return path, nil
}

// fetchXrayDigestSHA256 downloads the .dgst sidecar XTLS publishes next to each
// release asset and returns the SHA2-256 hex digest it lists.
func (s *ServerService) fetchXrayDigestSHA256(client *http.Client, dgstURL string) (string, error) {
	req, reqErr := http.NewRequestWithContext(context.Background(), http.MethodGet, dgstURL, nil)
	if reqErr != nil {
		return "", fmt.Errorf("download xray checksum: %w", reqErr)
	}
	resp, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("download xray checksum: %w", err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("download xray checksum: unexpected HTTP %d", resp.StatusCode)
	}
	raw, err := io.ReadAll(io.LimitReader(resp.Body, maxXrayDigestBytes))
	if err != nil {
		return "", fmt.Errorf("download xray checksum: %w", err)
	}
	return parseXrayDigestSHA256(raw)
}

// parseXrayDigestSHA256 extracts the lowercase SHA2-256 hex from an XTLS .dgst
// file, whose lines are "ALGO= <hex>" (the relevant one being "SHA2-256= ...").
func parseXrayDigestSHA256(dgst []byte) (string, error) {
	for line := range strings.SplitSeq(string(dgst), "\n") {
		rest, ok := strings.CutPrefix(strings.TrimSpace(line), "SHA2-256=")
		if !ok {
			continue
		}
		h := strings.ToLower(strings.TrimSpace(rest))
		if len(h) != 64 {

View on GitHub (pinned to ad32144c42)

Solutions

1. Verify https://github.com/XTLS/Xray-core/releases/download/<version>/<file>.dgst exists in a browser
2. Choose a newer version that ships .dgst sidecars
3. For 429, wait before retrying; slow the update cadence

if resp, err := client.Head(dgstURL); err == nil && resp.StatusCode == http.StatusNotFound {
    // this version predates .dgst publishing — pick a newer release
}

When it happens

Trigger: Updating to a legacy Xray version released before XTLS started publishing .dgst files (404); hitting GitHub's asset-CDN rate limit on the second request (429); proxy blocking the sidecar.

Common situations: Pinning old Xray versions for compatibility; automated updaters making many sequential downloads.

Related errors

• GitHub API error: %s
• GitHub API returned status %d: %s
• download xray: unexpected HTTP %d
• Xray update aborted: the downloaded archive does not match t
• xray checksum: malformed SHA2-256 entry in digest

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