TechnitiumSoftware/DnsServer · error · ArgumentException

DNS-over-HTTP Real IP header name cannot exceed 255 characte

Error message

DNS-over-HTTP Real IP header name cannot exceed 255 characters.

What it means

Thrown by the DnsOverHttpRealIpHeader property setter when the supplied header name exceeds 255 characters. The library uses this header name (default "X-Real-IP") to read the originating client IP from a reverse-proxy DoH request, and 255 is the practical maximum length for an HTTP header field name token. Passing an over-long string is treated as a configuration error rather than silently truncating it.

Source

Thrown at DnsServerCore/Dns/DnsServer.cs:7841

                    _dnsReverseProxyNetworkACL = value;
            }
        }

        public string DnsTlsCertificatePath
        { get { return _dnsTlsCertificatePath; } }

        public string DnsTlsCertificatePassword
        { get { return _dnsTlsCertificatePassword; } }

        public string DnsOverHttpRealIpHeader
        {
            get { return _dnsOverHttpRealIpHeader; }
            set
            {
                if (string.IsNullOrEmpty(value))
                    _dnsOverHttpRealIpHeader = "X-Real-IP";
                else if (value.Length > 255)
                    throw new ArgumentException("DNS-over-HTTP Real IP header name cannot exceed 255 characters.", nameof(DnsOverHttpRealIpHeader));
                else if (value.Contains(' '))
                    throw new ArgumentException("DNS-over-HTTP Real IP header name cannot contain invalid characters.", nameof(DnsOverHttpRealIpHeader));
                else
                    _dnsOverHttpRealIpHeader = value;
            }
        }

        public IReadOnlyDictionary<string, TsigKey> TsigKeys
        {
            get { return _tsigKeys; }
            set
            {
                if ((value is null) || (value.Count == 0))
                    _tsigKeys = null;
                else if (value.Count > byte.MaxValue)
                    throw new ArgumentOutOfRangeException(nameof(TsigKeys), "TSIG keys cannot have more than 255 entries.");
                else
                    _tsigKeys = value;

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Pass a single, well-formed header name such as "X-Real-IP" or "X-Forwarded-For" that is far under 255 chars.
2. If you only need the default behavior, set the property to null or empty string so it auto-defaults to "X-Real-IP".
3. Double-check you are assigning the header NAME, not the resolved client IP or a list of headers.

Example fix

// before
server.DnsOverHttpRealIpHeader = "203.0.113.5, 198.51.100.2"; // accidentally assigned a value

// after
server.DnsOverHttpRealIpHeader = "X-Real-IP";

static string SanitizeRealIpHeader(string value)
{
    if (string.IsNullOrEmpty(value)) return null; // let the setter apply its default
    if (value.Length > 255)
        throw new InvalidOperationException("DoH real-IP header name must be <= 255 characters.");
    return value;
}

server.DnsOverHttpRealIpHeader = SanitizeRealIpHeader(configHeader);

static bool IsValidRealIpHeader(string value) =>
    string.IsNullOrEmpty(value) || (value.Length <= 255 && !value.Contains(' '));

try { server.DnsOverHttpRealIpHeader = headerName; }
catch (ArgumentException ex) when (ex.ParamName == nameof(server.DnsOverHttpRealIpHeader))
{
    logger.Warn("Invalid DoH real-IP header name; falling back to default.");
    server.DnsOverHttpRealIpHeader = null; // triggers built-in default
}

When it happens

Trigger: Setting DnsServer.DnsOverHttpRealIpHeader to any non-empty string whose Length > 255. This commonly happens when a developer accidentally assigns the header VALUE (e.g. a full IP list or a long proxy chain string) into the NAME field, or pastes a multi-header config blob.

Common situations: Confusing the header name with its value; copy-pasting an entire nginx/apache config line; feeding a JSON/concatenated set of forwarded headers into a single property; migrating from a proxy that exposes a composite header.

Related errors

• DNS-over-HTTP Real IP header name cannot contain invalid cha
• TSIG keys cannot have more than 255 entries.
• Valid range is from 1 to 10.
• Valid range is from 1 to 4.
• Valid range is from 10 to 30.

AI-assisted analysis of TechnitiumSoftware/DnsServer@d0484b6c1e (2026-08-13). Data as JSON: /api/errors/463e833222360638. Report an issue: GitHub.