What causes "empty HTTP header value: + key" in XTLS/Xray-core?

Replace the null value with an array of strings, e.g. "User-Agent": ["curl/8"] .

empty HTTP header value: + key

Error message

empty HTTP header value:  + key

What it means

Thrown while building an HTTP transport request config (HTTPTransportConfig.Build in transport_method.go): a key in the "headers" map has a nil value. Headers map from string to *[]string (json string array); JSON null (or a shape that unmarshals to nil) for any header triggers this error, which is decorated with .AtError() severity.

Source

Thrown at infra/conf/transport_method.go:125

	if len(v.Version) > 0 {
		config.Version = &http.Version{Value: v.Version}
	}

	if len(v.Method) > 0 {
		config.Method = &http.Method{Value: v.Method}
	}

	if len(v.Path) > 0 {
		config.Uri = append([]string(nil), v.Path...)
	}

	if len(v.Headers) > 0 {
		config.Header = make([]*http.Header, 0, len(v.Headers))
		headerNames := sortMapKeys(v.Headers)
		for _, key := range headerNames {
			value := v.Headers[key]
			if value == nil {
				return nil, errors.New("empty HTTP header value: " + key).AtError()
			}
			config.Header = append(config.Header, &http.Header{
				Name:  key,
				Value: append([]string(nil), (*value)...),
			})
		}
	}

	return config, nil
}

type AuthenticatorResponse struct {
	Version string                 `json:"version"`
	Status  string                 `json:"status"`
	Reason  string                 `json:"reason"`
	Headers map[string]*StringList `json:"headers"`
}

View on GitHub (pinned to 7d214f8b09)

Solutions

Replace the null value with an array of strings, e.g. "User-Agent": ["curl/8"] .
Or delete the header key entirely if the header should not be sent.
Check config-generation templates for conditionals that emit null.

Example fix

// before
"headers": { "User-Agent": null }
// after
"headers": { "User-Agent": ["Mozilla/5.0"] }

Defensive patterns

Strategy: validation

Validate before calling

func httpRequestHeadersOK(ts map[string]any) bool {
    req, _ := ts["request"].(map[string]any)
    headers, _ := req["headers"].(map[string]any)
    for _, v := range headers {
        if v == nil { return false }
        if _, ok := v.([]any); !ok { return false }
    }
    return true
}

Try / catch

if err := buildHTTPTransport(raw); err != nil {
    if strings.Contains(err.Error(), "empty HTTP header value") {
        // the header name is appended to the message; fix that key
    }
    return err
}

Prevention

Never use null for a header; delete the key instead.
In templates, render conditional headers only when a value exists (omit key otherwise).
Schema-validate that every headers value is an array of strings.

When it happens

Trigger: "headers": { "User-Agent": null }" under an http transport settings block (request path headers).

Common situations: Writing "null" for a header you want to remove instead of deleting the key; template engines (Helm/Jinja) rendering empty values as null; merging configs where a header override is absent and serialized as null.

Related errors

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