What causes "xray version %q is not in the fetched release list" in MHSanaei/3x-ui?

Refresh the version list in the panel and re-select the version from it

xray version %q is not in the fetched release list

Error message

xray version %q is not in the fetched release list

What it means

Returned by UpdateXray when the requested version is not present in the list fetched from GetXrayVersions(). The version must be chosen from the fetched GitHub release list — anything else (typo, 'v' prefix mismatch, a prerelease not in the list, a version published after the list was fetched) is rejected before xray is stopped or anything is downloaded. It protects against stopping the service for an impossible update.

Source

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

		if !ok {
			continue
		}
		h := strings.ToLower(strings.TrimSpace(rest))
		if len(h) != 64 {
			return "", fmt.Errorf("xray checksum: malformed SHA2-256 entry in digest")
		}
		return h, nil
	}
	return "", fmt.Errorf("xray checksum: no SHA2-256 entry in digest")
}

func (s *ServerService) UpdateXray(version string) error {
	versions, err := s.GetXrayVersions()
	if err != nil {
		return err
	}
	if !slices.Contains(versions, version) {
		return fmt.Errorf("xray version %q is not in the fetched release list", version)
	}

	// 1. Stop xray before doing anything
	if err := s.StopXrayService(); err != nil {
		logger.Warning("failed to stop xray before update:", err)
	}

	// 2. Download the zip
	zipFileName, err := s.downloadXRay(version)
	if err != nil {
		return err
	}
	defer os.Remove(zipFileName)

	zipFile, err := os.Open(zipFileName)
	if err != nil {
		return err
	}

View on GitHub (pinned to ad32144c42)

Solutions

Refresh the version list in the panel and re-select the version from it
Match the exact GitHub tag spelling (including the leading 'v' if the list shows it)
If rate-limited earlier, wait for the window to reset so the full list is fetched

Defensive patterns

Strategy: validation

Validate before calling

versions, err := s.GetXrayVersions()
if err != nil {
    return err
}
if !slices.Contains(versions, version) {
    return fmt.Errorf("version %q not offered; refresh the list and pick from it", version)
}

Prevention

Always re-fetch the release list immediately before an update, not at page load
Pass versions verbatim from the list to the update call — no hand-typing tags
Normalize tag spelling (leading 'v') at one place in the code

When it happens

Trigger: Calling UpdateXray('2.1.0') when releases are tagged 'v2.1.0' or vice versa; the UI's version list is stale (fetched before a new release was published); selecting a draft/prerelease that the releases API omits; whitespace in the version string.

Common situations: User pastes a version from the Xray blog that differs from the GitHub tag; the panel page was open for hours and a new release came out; API returned a partial list during rate limiting.

Related errors

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