XTLS/Xray-core · error · errors.Error

failed to fill out header

Error message

failed to fill out header

What it means

Before opening the tunnel, the HTTP outbound templates the configured custom headers via fillRequestHeader. That helper can fail on missing session metadata (see the dedicated error for that) or on template evaluation problems; the outer Process wraps any such failure as "failed to fill out header".

Source

Thrown at proxy/http/client.go:100

	}

	server := c.server
	dest := server.Destination
	user := server.User
	var conn stat.Connection

	mbuf, _ := link.Reader.ReadMultiBuffer()
	len := mbuf.Len()
	firstPayload := bytespool.Alloc(len)
	mbuf, _ = buf.SplitBytes(mbuf, firstPayload)
	firstPayload = firstPayload[:len]

	buf.ReleaseMulti(mbuf)
	defer bytespool.Free(firstPayload)

	header, err := fillRequestHeader(ctx, c.header)
	if err != nil {
		return errors.New("failed to fill out header").Base(err)
	}

	if err := retry.ExponentialBackoff(5, 100).On(func() error {
		netConn, err := setUpHTTPTunnel(ctx, dest, targetAddr, user, dialer, header, firstPayload)
		if netConn != nil {
			if _, ok := netConn.(*http2Conn); !ok {
				if _, err := netConn.Write(firstPayload); err != nil {
					netConn.Close()
					return err
				}
			}
			conn = stat.Connection(netConn)
		}
		return err
	}); err != nil {
		return errors.New("failed to find an available destination").Base(err)
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check the Base error from fillRequestHeader — it distinguishes missing metadata from other failures
2. Ensure the inbound attaches proper session metadata (stock Xray inbounds do)
3. If headers are not needed by the upstream proxy, remove settings.headers
4. Verify header template syntax matches supported variables (source, target)

```go
if len(cfg.Header) > 0 {
    if session.InboundFromContext(ctx) == nil {
        // skip header templating or attach metadata first
    }
}
```

```go
if _, err := fillRequestHeader(ctx, headers); err != nil {
    if strings.Contains(err.Error(), "missing inbound or outbound") { /* attach session metadata */ }
}
```

When it happens

Trigger: settings.headers[] configured on the HTTP outbound while the session context lacks inbound/outbound metadata, or a header value using template variables that cannot be evaluated for the current request.

Common situations: Header templating (e.g. X-Forwarded-For style headers) configured on an outbound that also handles traffic from inbounds which do not attach session metadata; empty headers array mixed with odd configs.

Related errors

• missing inbound or outbound metadata from context
• empty HTTP header value: + key
• no target server found
• failed to get server spec
• target not specified.

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