{"record":{"id":"4437c6b2298bf299","repo":"XTLS/Xray-core","slug":"failed-to-create-portal-worker","errorCode":null,"errorMessage":"failed to create portal worker","messagePattern":"failed to create portal worker","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/reverse/portal.go","lineNumber":82,"sourceCode":"\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\n\tif ob.Target.Network == net.Network_UDP && ob.OriginalTarget.Address != nil && ob.OriginalTarget.Address != ob.Target.Address {\n\t\tlink.Reader = &buf.EndpointOverrideReader{Reader: link.Reader, Dest: ob.Target.Address, OriginalDest: ob.OriginalTarget.Address}\n\t\tlink.Writer = &buf.EndpointOverrideWriter{Writer: link.Writer, Dest: ob.Target.Address, OriginalDest: ob.OriginalTarget.Address}\n\t}\n","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/reverse/portal.go#L64-L100","documentation":"Portal-side failure one step after mux client creation: NewPortalWorker(muxClient) failed. The constructor (see error 95) dispatches the internal control connection over the mux client (to the internal domain destination) and returns 'unable to dispatch control connection' when client.Dispatch returns false; that inner error is wrapped here. Without the control connection the worker cannot register/heartbeat, so the whole portal connection is rejected.","triggerScenarios":"The freshly created mux.ClientWorker refuses the control-connection dispatch — typically because the worker is already closed/full or its internal state rejected the new stream during tunnel setup.","commonSituations":"Bridge/portal version mismatch changing mux behavior, the carrier connection dropping microseconds after acceptance (worker closes before control connect), or resource limits where the worker immediately reports full. Usually transient and retried by the next bridge connection.","solutions":["Treat as transient first: the bridge's periodic monitor reconnects every few seconds; check whether errors persist or self-heal.","Upgrade both portal and bridge instances to matching xray-core versions so mux control semantics agree.","If persistent, inspect carrier link health (TLS, keepalives, MTU) between the two sides — a dying carrier kills the control dispatch."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"null // nothing caller-side prevents a control-dispatch failure inside the worker ctor","typeGuard":null,"tryCatchPattern":"if err := portal.HandleConnection(ctx, link); err != nil {\n    if strings.Contains(err.Error(), \"failed to create portal worker\") {\n        return scheduleBridgeReconnect(2 * time.Second) // monitor interval; treat as transient\n    }\n    return err\n}","preventionTips":["Expect the bridge monitor to re-establish tunnels; do not fail hard on one occurrence","Pin identical xray-core versions on portal and bridge","Watch carrier lifetime patterns (e.g. dies at fixed age -> NAT timeout; enable keepalive)"],"tags":["go","xray","reverse-proxy","mux","control-channel"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}