XTLS/Xray-core · error

unexpected network

Error message

unexpected network 

What it means

The mux server received a SessionStatusNew frame whose target network (TCP or UDP) does not match the network restriction attached to the context (session.AllowedNetworkFromContext, set by inbound sniffing/routing rules). Because one mux connection carries all substreams, this mismatch breaks the entire Mux connection, not just the substream.

Source

Thrown at common/mux/server.go:191

		}
	}
	errors.LogInfo(ctx, "received request for ", meta.Target)
	{
		msg := &log.AccessMessage{
			To:     meta.Target,
			Status: log.AccessAccepted,
			Reason: "",
		}
		if inbound := session.InboundFromContext(ctx); inbound != nil && inbound.Source.IsValid() {
			msg.From = inbound.Source
			msg.Email = inbound.User.Email
		}
		ctx = log.ContextWithAccessMessage(ctx, msg)
	}

	if network := session.AllowedNetworkFromContext(ctx); network != net.Network_Unknown {
		if meta.Target.Network != network {
			return errors.New("unexpected network ", meta.Target.Network) // it will break the whole Mux connection
		}
	}

	if meta.GlobalID != [8]byte{} { // MUST ignore empty Global ID
		mb, err := NewPacketReader(reader, &meta.Target).ReadMultiBuffer()
		if err != nil {
			return err
		}
		XUDPManager.Lock()
		x := XUDPManager.Map[meta.GlobalID]
		if x == nil {
			x = &XUDP{GlobalID: meta.GlobalID}
			XUDPManager.Map[meta.GlobalID] = x
			XUDPManager.Unlock()
		} else {
			if x.Status == Initializing { // nearly impossible
				XUDPManager.Unlock()
				errors.LogWarningInner(ctx, errors.New("conflict"), "XUDP hit ", meta.GlobalID)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Remove or widen the network restriction (set inbound/route rule "network" to "tcp,udp") if both transports are expected over mux.
2. Disable mux for UDP traffic on the client, or disable XUDP, so UDP never rides the constrained connection.
3. Add a separate outbound/inbound pair without the network restriction for the other transport.
4. Confirm the rule that sets the allowed network via routing logs before changing config.

Example fix

// inbound config: allow both transports when mux is used
// before
"inbounds": [{ "port": 443, "protocol": "vless", "settings": { "decryption": "none" }, "streamSettings": { "network": "tcp" } }]
// after
"inbounds": [{ "port": 443, "protocol": "vless", "settings": { "decryption": "none" }, "streamSettings": { "network": "tcp,udp" } }]

// Before multiplexing, verify the transport is allowed by your inbound/route config:
allowed := net.Network_TCP // example restriction
if target.Network != allowed {
    return fmt.Errorf("cannot mux %v over %v-only inbound", target.Network, allowed)
}

if err := w.handleStatusNew(ctx, &meta, reader); err != nil {
    if strings.Contains(err.Error(), "unexpected network") {
        // config issue: relax the network restriction or stop muxing the other transport
    }
    return err // intentionally breaks the mux connection
}

When it happens

Trigger: An inbound or routing rule restricts the connection to, say, TCP only, but the client multiplexes a UDP request (or vice versa) over the same mux connection.

Common situations: Routing/inbound config with network constraints (e.g. "network": "tcp" on an inbound or a routing rule) combined with a client that enables mux and sends both TCP and UDP traffic; XUDP over a TCP-only inbound.

Related errors

• balancing strategy returns empty tag
• failed to check code
• no valid ip matcher
• XUDP new
• failed to dispatch request.

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