XTLS/Xray-core · error

unknown network: {network}

Error message

unknown network: {network}

What it means

Thrown by the SOCKS inbound's Network() dispatcher when the connection network is not TCP. The inbound only implements the TCP branch (with UDP handled inside via UDP ASSOCIATE over TCP), so a UDP packet delivered directly to Network() hits the default case.

Source

Thrown at proxy/socks/server.go:93

	}

	switch network {
	case net.Network_TCP:
		firstbyte := make([]byte, 1)
		if n, err := conn.Read(firstbyte); n == 0 {
			if goerrors.Is(err, io.EOF) {
				errors.LogInfo(ctx, "Connection closed immediately, likely health check connection")
				return nil
			}
			return errors.New("failed to read from connection").Base(err)
		}
		if firstbyte[0] != 5 && firstbyte[0] != 4 { // Check if it is Socks5/4/4a
			errors.LogDebug(ctx, "Not Socks request, try to parse as HTTP request")
			return s.httpServer.ProcessWithFirstbyte(ctx, network, conn, dispatcher, firstbyte...)
		}
		return s.processTCP(ctx, conn, dispatcher, firstbyte)
	default:
		return errors.New("unknown network: ", network)
	}
}

func (s *Server) processTCP(ctx context.Context, conn stat.Connection, dispatcher routing.Dispatcher, firstbyte []byte) error {
	plcy := s.policy()
	if err := conn.SetReadDeadline(time.Now().Add(plcy.Timeouts.Handshake)); err != nil {
		errors.LogInfoInner(ctx, err, "failed to set deadline")
	}

	inbound := session.InboundFromContext(ctx)
	if inbound == nil || !inbound.Gateway.IsValid() {
		return errors.New("inbound gateway not specified")
	}

	svrSession := &ServerSession{
		config:       s.config,
		address:      inbound.Gateway.Address,
		port:         inbound.Gateway.Port,

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Ensure the socks inbound's streamSettings/listener only binds TCP (remove any UDP listen setting).
2. For raw UDP ingress use a dokodemo-door inbound with network UDP instead of socks.
3. If writing custom code that calls this handler, only pass net.Network_TCP connections.
4. Upgrade the launcher/panel generating the config to one that emits valid SOCKS inbound configs.

Example fix

// before: trying to feed UDP straight into a socks inbound
{ "protocol": "socks", "port": 1080, "settings": { "udp": true } }

// after: socks over TCP; UDP arrives via UDP ASSOCIATE (or use dokodemo for raw UDP)
{ "protocol": "socks", "port": 1080, "settings": { "auth": "noauth" } }

if network != net.Network_TCP {
	return errors.New("socks inbound accepts TCP only; UDP arrives via UDP ASSOCIATE")
}

When it happens

Trigger: The framework calls Process/Network with net.Network_UDP (or any non-TCP network) on this inbound — e.g. misconfigured listener binding the SOCKS inbound to a UDP socket, or an internal routing rewrite delivering UDP directly.

Common situations: Copying adoket/dokodemo style config where the inbound listens on UDP; a bug in a custom caller invoking Process with a UDP connection; version skew between core and a third-party launcher generating invalid inbound config.

Related errors

• Shadowsocks password is not specified.
• unknown cipher method:
• shadowsocks 2022 (multi-user): missing server method
• SOCKS settings: "servers" should have one and only one membe
• SOCKS servers: "users" should have one member at most. Multi

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