{"record":{"id":"c6b47e7a3b291c42","repo":"XTLS/Xray-core","slug":"failed-to-process-outbound-traffic","errorCode":null,"errorMessage":"failed to process outbound traffic","messagePattern":"failed to process outbound traffic","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/proxyman/outbound/handler.go","lineNumber":253,"sourceCode":"\t\t\treturn\n\t\t}\n\t\tif h.mux.Enabled {\n\t\t\ttest(h.mux.Dispatch(ctx, link))\n\t\t\treturn\n\t\t}\n\t}\nout:\n\terr := h.proxy.Process(ctx, link, h)\n\tvar errC error\n\tif err != nil {\n\t\terrC = errors.Cause(err)\n\t\tif goerrors.Is(errC, io.EOF) || goerrors.Is(errC, io.ErrClosedPipe) || goerrors.Is(errC, context.Canceled) {\n\t\t\terr = nil\n\t\t}\n\t}\n\tif err != nil {\n\t\t// Ensure outbound ray is properly closed.\n\t\terr := errors.New(\"failed to process outbound traffic\").Base(err)\n\t\tsession.SubmitOutboundErrorToOriginator(ctx, err)\n\t\terrors.LogInfo(ctx, err.Error())\n\t\tcommon.Interrupt(link.Writer)\n\t} else {\n\t\tif errC != nil && goerrors.Is(errC, io.ErrClosedPipe) {\n\t\t\tcommon.Interrupt(link.Writer)\n\t\t} else {\n\t\t\tcommon.Close(link.Writer)\n\t\t}\n\t}\n\tcommon.Interrupt(link.Reader)\n}\n\nfunc (h *Handler) DestIpAddress() net.IP {\n\treturn internet.DestIpAddress()\n}\n\n// Dial implements internet.Dialer.","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/proxyman/outbound/handler.go#L235-L271","documentation":"The primary outbound dispatch failure: the underlying proxy's Process(ctx, link, h) returned a non-nil error that is not one of the benign causes (io.EOF, io.ErrClosedPipe, context.Canceled), which are normalized to nil just above. The logged message wraps the real cause via .Base; the writer is interrupted and the error reported to the session originator.","triggerScenarios":"h.proxy.Process fails for a connection that already passed DNS/mux handling: protocol errors from the remote server (handshake failure, auth failure, unsupported protocol), network errors dialing or mid-stream (connection reset, timeout), TLS failures, or the remote proxy closing with an error. Any cause except io.EOF / io.ErrClosedPipe / context.Canceled reaches this branch.","commonSituations":"Wrong UUID/password or altered protocol settings vs the server, TLS certificate/reality misconfiguration, server reachable but behind a CDN that rejects the path, NAT/firewall resetting long connections, or clock skew breaking time-bound handshakes. This is the generic envelope, so the Base cause in the log is the actual diagnostic.","solutions":["Inspect the full log line: the Base() error names the real failure (timeout, TLS, handshake, auth) — fix that layer first.","Verify client/server protocol settings match exactly (protocol version, UUID/password, encryption, transport, TLS/REALITY parameters, SNI, path).","Test raw reachability of the server's transport port (tcping/nc) and, for TLS/REALITY, confirm certificate and destination config; check server-side logs for the matching failure.","For timeout-type inner errors, review sockopt dialer settings, mark/routing table, and MTU; for reset errors, check for ISP interference and switch transport (e.g. to grpc/ws over TLS).","Reproduce with loglevel debug on both ends to capture the exact stage that fails."],"exampleFix":"// no code fix; diagnosis example\n// log: [Info] proxy/vless/outbound: failed to process outbound traffic > tls: handshake failure\n// fix: align client streamSettings with server, e.g.\n// before: \"security\": \"tls\", \"tlsSettings\": { \"serverName\": \"wrong.example\" }\n// after:  \"security\": \"tls\", \"tlsSettings\": { \"serverName\": \"actual.example\" }","handlingStrategy":"retry","validationCode":"// Pre-validate the remote before routing user traffic through it\nif err := probeOutbound(ctx, handlerTag, probeDest); err != nil {\n    return routeViaFallback(ctx, link)\n}","typeGuard":null,"tryCatchPattern":"// Classify cause before deciding: benign closes vs real failures\nif err := dispatch(ctx, link); err != nil && strings.Contains(err.Error(), \"failed to process outbound traffic\") {\n    switch {\n    case isTimeoutCause(err): return retryWithBackoff(ctx, link, 3)\n    case isAuthCause(err):   return nil // config problem; surface to user, no retry\n    default:                 return fallbackOutbound.Dispatch(ctx, link)\n    }\n}","preventionTips":["Validate protocol/transport/TLS settings against the server before going live","Run active health probes (api observatory or balancer with leastping) on outbounds","Treat resets/timeouts differently: retry the former, fix config for the latter","Keep a known-good fallback outbound for automatic degradation"],"tags":["go","xray","outbound","proxy","connection"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}