{"record":{"id":"9602a64c3bbc51dc","repo":"XTLS/Xray-core","slug":"unable-to-find-an-available-mux-client","errorCode":null,"errorMessage":"unable to find an available mux client","messagePattern":"unable to find an available mux client","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"common/mux/client.go","lineNumber":41,"sourceCode":")\n\ntype ClientManager struct {\n\tEnabled bool // whether mux is enabled from user config\n\tPicker  WorkerPicker\n}\n\nfunc (m *ClientManager) Dispatch(ctx context.Context, link *transport.Link) error {\n\tfor i := 0; i < 16; i++ {\n\t\tworker, err := m.Picker.PickAvailable()\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif worker.Dispatch(ctx, link) {\n\t\t\treturn nil\n\t\t}\n\t}\n\n\treturn errors.New(\"unable to find an available mux client\").AtWarning()\n}\n\ntype WorkerPicker interface {\n\tPickAvailable() (*ClientWorker, error)\n}\n\ntype IncrementalWorkerPicker struct {\n\tFactory ClientWorkerFactory\n\n\taccess      sync.Mutex\n\tworkers     []*ClientWorker\n\tcleanupTask *task.Periodic\n}\n\nfunc (p *IncrementalWorkerPicker) cleanupFunc() error {\n\tp.access.Lock()\n\tdefer p.access.Unlock()\n","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/mux/client.go#L23-L59","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"// before\n\"streamSettings\": {}, \"mux\": {\"enabled\": true, \"concurrency\": -1}\n\n// after\n\"mux\": {\"enabled\": true, \"concurrency\": 8}","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := muxClient.Dispatch(ctx, link); err != nil && strings.Contains(err.Error(), \"unable to find an available mux client\") {\n    log.Warn(\"mux exhausted; retrying without mux\")\n    directLink(ctx, link) // fall back to non-multiplexed dispatch\n}","preventionTips":["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."],"tags":["mux","concurrency","proxy","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}