TechnitiumSoftware/DnsServer · error · ArgumentException

DNS-over-HTTP Real IP header name cannot contain invalid cha

Error message

DNS-over-HTTP Real IP header name cannot contain invalid characters.

What it means

Thrown by the DnsOverHttpRealIpHeader setter when the supplied header name contains a space character. HTTP header field names must be RFC 7230 tokens (no whitespace), so the library rejects any value containing ' ' as invalid. Note the check is specifically for the space character — other non-token characters are not caught here.

Source

Thrown at DnsServerCore/Dns/DnsServer.cs:7843

        }

        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. Use the canonical hyphenated form, e.g. "X-Real-IP" or "X-Forwarded-For".
2. Trim whitespace from config-sourced values before assigning: value.Trim().
3. Set to null/empty to fall back to the built-in default "X-Real-IP".

Example fix

// before
server.DnsOverHttpRealIpHeader = "X Forwarded For";

// after
server.DnsOverHttpRealIpHeader = "X-Forwarded-For";

static string CleanHeaderName(string value) =>
    string.IsNullOrWhiteSpace(value) ? null : value.Trim();

server.DnsOverHttpRealIpHeader = CleanHeaderName(configHeader);

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

try { server.DnsOverHttpRealIpHeader = headerName; }
catch (ArgumentException ex) when (ex.ParamName == nameof(server.DnsOverHttpRealIpHeader))
{
    server.DnsOverHttpRealIpHeader = "X-Real-IP";
}

When it happens

Trigger: Setting DnsOverHttpRealIpHeader to a string that contains a space, e.g. "X Real IP", "X-Forwarded-For :", or a value with trailing/leading whitespace from a config trim failure.

Common situations: Typing the header with spaces instead of hyphens; reading the value from an environment variable or config file without trimming; concatenating header name and value by mistake.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• DNS-over-HTTP Real IP header name cannot exceed 255 characte
• 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/6306729a057d5ef2. Report an issue: GitHub.