What causes "unable to find an available mux client" in XTLS/Xray-core?

Raise mux concurrency (e.g. "mux": {"concurrency": 16} or higher) so fewer workers saturate, or disable mux to test whether the underlying connection is healthy.

XTLS/Xray-core · warning

unable to find an available mux client

Error message

unable to find an available mux client

What it means

ClientManager.Dispatch tries up to 16 times to pick a mux client worker and hand it the link; if every PickAvailable() either errors or the worker refuses Dispatch, the connection cannot be multiplexed and this warning-level error is returned. It signals mux worker pool exhaustion or a broken picker, not a protocol error on the wire.

Source

Thrown at common/mux/client.go:41

)

type ClientManager struct {
	Enabled bool // whether mux is enabled from user config
	Picker  WorkerPicker
}

func (m *ClientManager) Dispatch(ctx context.Context, link *transport.Link) error {
	for i := 0; i < 16; i++ {
		worker, err := m.Picker.PickAvailable()
		if err != nil {
			return err
		}
		if worker.Dispatch(ctx, link) {
			return nil
		}
	}

	return errors.New("unable to find an available mux client").AtWarning()
}

type WorkerPicker interface {
	PickAvailable() (*ClientWorker, error)
}

type IncrementalWorkerPicker struct {
	Factory ClientWorkerFactory

	access      sync.Mutex
	workers     []*ClientWorker
	cleanupTask *task.Periodic
}

func (p *IncrementalWorkerPicker) cleanupFunc() error {
	p.access.Lock()
	defer p.access.Unlock()

View on GitHub (pinned to 7d214f8b09)

Solutions

Raise mux concurrency (e.g. "mux": {"concurrency": 16} or higher) so fewer workers saturate, or disable mux to test whether the underlying connection is healthy.
Check server logs/connection limits — if new worker connections cannot be established, every pick fails.
Upgrade client and server to matching Xray versions for mux frame compatibility.
If sustained, keep mux disabled for that outbound (many sites misbehave with multiplexing).

Example fix

// before
"streamSettings": {}, "mux": {"enabled": true, "concurrency": -1}

// after
"mux": {"enabled": true, "concurrency": 8}

Defensive patterns

Strategy: fallback

Try / catch

if err := muxClient.Dispatch(ctx, link); err != nil && strings.Contains(err.Error(), "unable to find an available mux client") {
    log.Warn("mux exhausted; retrying without mux")
    directLink(ctx, link) // fall back to non-multiplexed dispatch
}

Prevention

Set explicit mux concurrency (8–16) matched to your workload instead of unbounded defaults.
Monitor worker-establishment failures server-side; exhausted pickers usually stem from the underlying proxy failing.
Provide a non-mux fallback path in connection handling for high-burst traffic.

When it happens

Trigger: Mux (x-mux) enabled with high concurrency; all existing ClientWorkers at capacity and the IncrementalWorkerPicker failing to create new ones (e.g. underlying inbound proxy failing, connection limits reached); KeepAlive- Interval/capacity settings too low.

Common situations: Mux enabled on outbounds under heavy tab/browser load; server-side connection limits causing new worker establishment to fail; misconfigured mux.concurrency/-only variants across client/server version skew.

Related errors

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/9602a64c3bbc51dc. Report an issue: GitHub.