MHSanaei/3x-ui · error

Failed to start test xray instance: %w

Error message

Failed to start test xray instance: %w

What it means

proc.Start() failed and errors.Is(err, fs.ErrNotExist) matched, meaning the xray binary itself was not found at the expected path. The code marks it non-retryable (retryPerItem=false) because every per-item retry would hit the same missing binary. This is the outbound HTTP probe's dedicated 'xray not installed / wrong path' signal.

Source

Thrown at internal/web/service/outbound/probe_http.go:306

		return false, fmt.Errorf("Failed to create test config path: %w", err)
	}
	defer os.Remove(configPath)

	proc := newBatchProcess(cfg, configPath)
	defer func() {
		if proc.IsRunning() {
			_ = proc.Stop()
		}
	}()

	// Free the reserved ports just before xray binds them; the window is
	// milliseconds, and a lost race makes xray exit fast, which surfaces
	// below and triggers the per-item retry with fresh ports.
	release()
	if err := proc.Start(); err != nil {
		if errors.Is(err, fs.ErrNotExist) {
			// Binary missing — per-item retries would all fail the same way.
			return false, fmt.Errorf("Failed to start test xray instance: %w", err)
		}
		return true, fmt.Errorf("Failed to start test xray instance: %w", err)
	}

	if err := waitForPortsReady(proc, ports, batchPortsReadyTimeout); err != nil {
		return err.exited, err
	}

	sem := make(chan struct{}, httpProbeConcurrency)
	var wg sync.WaitGroup
	for i := range items {
		wg.Add(1)
		go func(it *httpBatchItem, port int) {
			defer wg.Done()
			sem <- struct{}{}
			defer func() { <-sem }()
			probeThroughSocks(port, testURL, httpProbeTimeout, realDelay, it.result)
		}(items[i], ports[i])

View on GitHub (pinned to ad32144c42)

Solutions

1. Verify the xray binary exists in the bin folder (ls <bin folder>) and reinstall it from the panel's xray version settings
2. Fix XUI_BIN_FOLDER so it points at the directory that actually contains xray
3. Check panel startup logs for an earlier xray download/update failure

Example fix

# before
ls /usr/local/x-ui/bin/   # empty -> probe fails with fs.ErrNotExist

# after
# reinstall/update xray via panel (Settings -> Xray version) or:
cd /usr/local/x-ui/bin && wget https://github.com/XTLS/Xray-core/releases/download/vX.Y.Z/xray-linux-amd64 ... && chmod +x xray

if _, err := os.Stat(filepath.Join(config.GetBinFolderPath(), "xray")); errors.Is(err, fs.ErrNotExist) {
    return errors.New("xray binary missing; install it before testing outbounds")
}

_, err := runHTTPProbeBatch(items, all, url, true)
if err != nil && errors.Is(err, fs.ErrNotExist) {
    // the %w chain preserves ErrNotExist: prompt user to install/update xray
}

When it happens

Trigger: Clicking 'test' on outbounds when the managed xray binary is absent — fresh install where the download step failed, XUI_BIN_FOLDER misconfigured, or the binary was deleted/renamed out from under the panel.

Common situations: Panel installed without xray asset download (offline install script); custom bin folder pointing to an empty directory; binary removed by an antivirus or a failed update.

Related errors

• Failed to create test config path: %w
• Failed to reserve test ports: %w
• local xray is not running
• xray is not running
• xray is already running

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