{"record":{"id":"411ee99cd3f8830d","repo":"XTLS/Xray-core","slug":"failed-to-create-mux-client-worker","errorCode":null,"errorMessage":"failed to create mux client worker","messagePattern":"failed to create mux client worker","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"app/reverse/portal.go","lineNumber":77,"sourceCode":"\t\ttag:    p.tag,\n\t})\n}\n\nfunc (p *Portal) Close() error {\n\treturn p.ohm.RemoveHandler(context.Background(), p.tag)\n}\n\nfunc (p *Portal) HandleConnection(ctx context.Context, link *transport.Link) error {\n\toutbounds := session.OutboundsFromContext(ctx)\n\tob := outbounds[len(outbounds)-1]\n\tif ob == nil {\n\t\treturn errors.New(\"outbound metadata not found\").AtError()\n\t}\n\n\tif isDomain(ob.Target, p.domain) {\n\t\tmuxClient, err := mux.NewClientWorker(*link, mux.ClientStrategy{})\n\t\tif err != nil {\n\t\t\treturn errors.New(\"failed to create mux client worker\").Base(err).AtWarning()\n\t\t}\n\n\t\tworker, err := NewPortalWorker(muxClient)\n\t\tif err != nil {\n\t\t\treturn errors.New(\"failed to create portal worker\").Base(err)\n\t\t}\n\n\t\tp.picker.AddWorker(worker)\n\n\t\tif _, ok := link.Reader.(*pipe.Reader); !ok {\n\t\t\tselect {\n\t\t\tcase <-ctx.Done():\n\t\t\tcase <-muxClient.WaitClosed():\n\t\t\t}\n\t\t}\n\t\treturn nil\n\t}\n","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/reverse/portal.go#L59-L95","documentation":"Portal-side failure to create the mux client that carries all tunneled connections over the single portal connection: mux.NewClientWorker(*link, mux.ClientStrategy{}) returned an error. Marked AtWarning because the tunnel setup failed but the instance keeps running. NewClientWorker can fail when the supplied link is already closed/broken or mux worker internals (pipe/queue init) fail.","triggerScenarios":"A connection dispatched to the portal whose target domain matches p.domain, but whose transport.Link reader/writer is unusable — e.g. the inbound connection died between accept and portal dispatch, or a custom caller passed an already-closed pipe pair to HandleConnection.","commonSituations":"Flaky upstream connections between bridge and portal dropping right at tunnel establishment; memory pressure or bugs in older core versions where client worker init fails; custom integrations reusing link objects. Rare in stock deployments.","solutions":["Check bridge-to-portal connectivity and stability (the underlying carrier connection must be healthy when the portal accepts it).","Upgrade xray-core; mux client worker initialization has had fixes across releases.","If embedding, verify the link passed to HandleConnection is freshly created and open, not shared or pre-closed."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Ensure the link is open before tunnel setup\nif link.Reader == nil || link.Writer == nil { return errors.New(\"invalid link for portal tunnel\") }\n// optionally probe: write a zero-length keepalive to detect dead links","typeGuard":null,"tryCatchPattern":"if err := portal.HandleConnection(ctx, link); err != nil {\n    if strings.Contains(err.Error(), \"failed to create mux client worker\") {\n        closeLink(link) // session is unusable; let the bridge reconnect fresh\n        return nil     // transient: next bridge connection retries\n    }\n    return err\n}","preventionTips":["Keep carrier (bridge<->portal) connections healthy: TCP keepalives, stable NAT","Run matched core versions on both ends","Alert on repeated occurrences rather than single failures — reconnects self-heal"],"tags":["go","xray","reverse-proxy","mux","reliability"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}