XTLS/Xray-core · critical

insufficient buffer:

Error message

insufficient buffer: 

What it means

After reading the declared meta length from the wire, the buffer holds fewer than 4 bytes, yet a mux frame header needs at least sessionID(2) + status(1) + option(1). The length prefix and actual bytes disagree — truncated or corrupted metadata.

Source

Thrown at common/mux/frame.go:136

	}
	if metaLen > 512 {
		return errors.New("invalid metalen ", metaLen).AtError()
	}

	b := buf.New()
	defer b.Release()

	if _, err := b.ReadFullFrom(reader, int32(metaLen)); err != nil {
		return err
	}
	return f.UnmarshalFromBuffer(b, readSourceAndLocal)
}

// UnmarshalFromBuffer reads a FrameMetadata from the given buffer.
// Visible for testing only.
func (f *FrameMetadata) UnmarshalFromBuffer(b *buf.Buffer, readSourceAndLocal bool) error {
	if b.Len() < 4 {
		return errors.New("insufficient buffer: ", b.Len())
	}

	f.SessionID = binary.BigEndian.Uint16(b.BytesTo(2))
	f.SessionStatus = SessionStatus(b.Byte(2))
	f.Option = bitmask.Byte(b.Byte(3))
	f.Target.Network = net.Network_Unknown

	if f.SessionStatus == SessionStatusNew || (f.SessionStatus == SessionStatusKeep && b.Len() > 4 &&
		TargetNetwork(b.Byte(4)) == TargetNetworkUDP) { // MUST check the flag first
		if b.Len() < 8 {
			return errors.New("insufficient buffer: ", b.Len())
		}
		network := TargetNetwork(b.Byte(4))
		b.Advance(5)

		addr, port, err := addrParser.ReadAddressPort(nil, b)
		if err != nil {
			return errors.New("failed to parse address and port").Base(err)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Verify both ends run compatible Xray versions with matching mux settings.
2. Check for transparent proxies/CDNs in the path that could truncate or alter the stream.
3. Disable mux for that outbound to isolate whether framing or transport is at fault.

err := frame.UnmarshalFromBuffer(b, false)
if err != nil && strings.Contains(err.Error(), "insufficient buffer") {
    closeMuxSession() // stream is corrupt; drop connection
    return err
}

When it happens

Trigger: A mux peer sending metaLen >= 1 but fewer than 4 bytes of body; mid-stream desynchronization after erroring frames; crafted/foreign data on the mux connection.

Common situations: Same roots as invalid metalen: mux pointed at non-mux server, connection cut mid-frame, or TLS/REALITY termination mismatch mangling the stream.

Related errors

• invalid metalen
• failed to parse address and port
• unknown network type:
• packet size too large:
• failed to read metadata

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