What causes "failed to write addons protobuf length" in XTLS/Xray-core?

Upgrade to an official xray-core release

failed to write addons protobuf length

Error message

failed to write addons protobuf length

What it means

While writing the XTLS Vision addons block, Xray writes the marshaled length as one byte into a preallocated buf.Buffer. WriteByte on an internal buffer fails only if the buffer is full (2048 bytes by default) — not reachable here since the buffer is fresh. Effectively an internal invariant check, not an expected runtime error.

Source

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

	"github.com/xtls/xray-core/common/buf"
	"github.com/xtls/xray-core/common/errors"
	"github.com/xtls/xray-core/common/protocol"
	"github.com/xtls/xray-core/common/session"
	"github.com/xtls/xray-core/proxy"
	"github.com/xtls/xray-core/proxy/vless"
	"google.golang.org/protobuf/proto"
)

func EncodeHeaderAddons(buffer *buf.Buffer, addons *Addons) error {
	switch addons.Flow {
	case vless.XRV:
		bytes, err := proto.Marshal(addons)
		if err != nil {
			return errors.New("failed to marshal addons protobuf value").Base(err)
		}
		if err := buffer.WriteByte(byte(len(bytes))); err != nil {
			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)

View on GitHub (pinned to 7d214f8b09)

Solutions

Upgrade to an official xray-core release
Collect logs and report upstream if reproducible

Defensive patterns

Strategy: try-catch

Try / catch

if err := encoding.EncodeHeaderAddons(buffer, addons); err != nil {
	// any addons encode failure is per-connection: log and close
	log.Warnf("addons encode: %v", err)
	return conn.Close()
}

Prevention

Treat encode-stage addons errors as internal bugs: upgrade builds
Avoid heavily modified forks that alter buffer sizing

When it happens

Trigger: Would require the header buffer to already be at capacity before encoding addons, which the call sequence prevents. Not user-triggerable through configuration.

Common situations: Should not occur; if it does, suspect a modified/forked xray build with changed buffer handling.

Related errors

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