XTLS/Xray-core · warning

failed to marshal addons protobuf value

Error message

failed to marshal addons protobuf value

What it means

When encoding a VLESS request header for the XTLS Vision flow (addons.Flow == vless.XRV), the Addons protobuf message is serialized with proto.Marshal. Marshaling an in-memory message essentially cannot fail for this schema (no required fields, no unknown overflow), so this error is a defensive internal invariant rather than an expected runtime condition.

Source

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

	"context"
	"io"
	"net"

	"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)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. If observed, upgrade both ends to matching official xray-core versions
2. Report the full log line with versions to xray-core maintainers
3. As a workaround, switch the flow off (remove "flow": "xtls-rprx-vision") to bypass addons encoding

if err := encoding.EncodeHeaderAddons(buffer, addons); err != nil {
	if strings.Contains(err.Error(), "failed to marshal addons") {
		// internal invariant: log and drop the connection, do not retry
		log.Warnf("addons marshal failed: %v", err)
		return conn.Close()
	}
	return err
}

When it happens

Trigger: Theoretically: a corrupted Addons message state or a protobuf runtime incompatibility after an upgrade mixing old/new builds on the wire path. In practice, users should not see it.

Common situations: Mixed xray versions or a fork with a modified addons.proto writing incompatible field numbers; memory corruption in a buggy fork.

Related errors

• failed to write addons protobuf value
• failed to write addons protobuf length
• VLESS "settings.flow" doesn't support "` + c.Flow + `" in th
• VLESS users: "flow" doesn't support "` + account.Flow + `" i
• VLESS users: "flow" doesn't support "{account.Flow}" in this

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