XTLS/Xray-core · warning

failed to read addons protobuf length

Error message

failed to read addons protobuf length

What it means

On the server side, decoding a VLESS request header first reads one byte of addons length from the connection. ReadFullFrom on the network reader fails when the connection provides zero bytes (EOF) or is reset/times out before the byte arrives. This usually means the client disconnected during handshake or is not a compatible VLESS client.

Source

Thrown at proxy/vless/encoding/addons.go:43

			return errors.New("failed to write addons protobuf length").Base(err)
		}
		if _, err := buffer.Write(bytes); err != nil {
			return errors.New("failed to write addons protobuf value").Base(err)
		}
	default:
		if err := buffer.WriteByte(0); err != nil {
			return errors.New("failed to write addons protobuf length").Base(err)
		}
	}

	return nil
}

func DecodeHeaderAddons(buffer *buf.Buffer, reader io.Reader) (*Addons, error) {
	addons := new(Addons)
	buffer.Clear()
	if _, err := buffer.ReadFullFrom(reader, 1); err != nil {
		return nil, errors.New("failed to read addons protobuf length").Base(err)
	}

	if length := int32(buffer.Byte(0)); length != 0 {
		buffer.Clear()
		if _, err := buffer.ReadFullFrom(reader, length); err != nil {
			return nil, errors.New("failed to read addons protobuf value").Base(err)
		}

		if err := proto.Unmarshal(buffer.Bytes(), addons); err != nil {
			return nil, errors.New("failed to unmarshal addons protobuf value").Base(err)
		}

		// Verification.
		switch addons.Flow {
		default:
		}
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Confirm the client targets the right port/protocol and both ends run compatible xray versions
2. Put VLESS behind a TLS/REALITY layer or use port hopping/reverse proxy health checks that send data
3. If caused by scanners, it is safe to log-and-ignore; the per-connection handshake fails cleanly
4. Check MTU/timeout settings if legitimate clients hit it mid-handshake

addons, err := encoding.DecodeHeaderAddons(buffer, reader)
if err != nil {
	if errors.Is(err, io.EOF) || strings.Contains(err.Error(), "failed to read addons protobuf length") {
		// peer disconnected mid-handshake (scanner/reset): log at debug, close
		return conn.Close()
	}
	return err
}

When it happens

Trigger: Client closes the connection right after TCP connect (port scanners, health probes like CDN/load-balancer TCP checks); TLS clients hitting a non-TLS VLESS port; middleboxes resetting connections; client xray version mismatched so the framing diverges.

Common situations: Exposing a VLESS inbound to the public internet (scanners constantly probe); misdirected traffic (https to the VLESS port); GFW/network interference; reverse proxy TCP health checks.

Related errors

• write handshake packet: %w
• write login start: %w
• read encryption request: %w
• bad encrypt request packet id
• write encryption response: %w

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