v2ray/v2ray-core · error

To avoid misunderstanding, you must fill in VLESS "flow" whe

Error message

To avoid misunderstanding, you must fill in VLESS "flow" when using XTLS.

What it means

Error "To avoid misunderstanding, you must fill in VLESS "flow" when using XTLS." thrown in v2ray/v2ray-core.

Source

Thrown at proxy/vless/outbound/outbound.go:158

			if !allowUDP443 && request.Port == 443 {
				return newError(requestAddons.Flow + " stopped UDP/443").AtInfo()
			}
			requestAddons.Flow = ""
		case protocol.RequestCommandTCP:
			if xtlsConn, ok := iConn.(*xtls.Conn); ok {
				xtlsConn.RPRX = true
				xtlsConn.SHOW = xtls_show
				xtlsConn.MARK = "XTLS"
				if requestAddons.Flow == vless.XRD {
					xtlsConn.DirectMode = true
				}
			} else {
				return newError(`failed to use ` + requestAddons.Flow + `, maybe "security" is not "xtls"`).AtWarning()
			}
		}
	default:
		if _, ok := iConn.(*xtls.Conn); ok {
			panic(`To avoid misunderstanding, you must fill in VLESS "flow" when using XTLS.`)
		}
	}

	sessionPolicy := h.policyManager.ForLevel(request.User.Level)
	ctx, cancel := context.WithCancel(ctx)
	timer := signal.CancelAfterInactivity(ctx, cancel, sessionPolicy.Timeouts.ConnectionIdle)

	clientReader := link.Reader // .(*pipe.Reader)
	clientWriter := link.Writer // .(*pipe.Writer)

	postRequest := func() error {
		defer timer.SetTimeout(sessionPolicy.Timeouts.DownlinkOnly)

		bufferWriter := buf.NewBufferedWriter(buf.NewWriter(conn))
		if err := encoding.EncodeRequestHeader(bufferWriter, request, requestAddons); err != nil {
			return newError("failed to encode request header").Base(err).AtWarning()
		}

View on GitHub (pinned to d80440f3d5)

Solutions

1. Add a "flow" field (e.g. "xtls-rprx-vision") to each VLESS user in the outbound when "security" is "xtls"; XTLS requires flow to be set explicitly.
2. If you do not intend to use XTLS, change the stream security from "xtls" to "tls" (or "reality") and remove any XTLS-only settings.
3. Make the flow value consistent between client and server VLESS configurations.

Example fix

{"protocol":"vless","settings":{"vnext":[{"address":"example.com","port":443,"users":[{"id":"uuid","encryption":"none","flow":"xtls-rprx-vision"}]}]},"streamSettings":{"security":"xtls"}}

When it happens

Trigger: Thrown at proxy/vless/outbound/outbound.go:158 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of v2ray/v2ray-core@d80440f3d5 (2026-08-15). Data as JSON: /api/errors/1b128f789938ad97. Report an issue: GitHub.