TechnitiumSoftware/DnsServer · error · ArgumentNullException

DNS optional protocols TLS certificate path cannot be null o

Error message

DNS optional protocols TLS certificate path cannot be null or empty.

What it means

Thrown by SetDnsTlsCertificate when dnsTlsCertificatePath is null or empty. This is the first guard before length and existence checks; it uses ArgumentNullException because the parameter contract is violated.

Source

Thrown at DnsServerCore/Dns/DnsServer.cs:1640

            _log.Write("DNS Server TLS certificate was loaded: " + tlsCertificatePath);
        }

        public void RemoveDnsTlsCertificate()
        {
            _dotSslServerAuthenticationOptions = null;
            _doqSslServerAuthenticationOptions = null;
            _dohSslServerAuthenticationOptions = null;

            _dnsTlsCertificatePath = null;
            _dnsTlsCertificatePassword = null;

            StopTlsCertificateUpdateTimer();
        }

        public void SetDnsTlsCertificate(string dnsTlsCertificatePath, string dnsTlsCertificatePassword = null, bool throwException = false)
        {
            if (string.IsNullOrEmpty(dnsTlsCertificatePath))
                throw new ArgumentNullException(nameof(dnsTlsCertificatePath), "DNS optional protocols TLS certificate path cannot be null or empty.");

            if (dnsTlsCertificatePath.Length > 255)
                throw new ArgumentException("DNS optional protocols TLS certificate path length cannot exceed 255 characters.", nameof(dnsTlsCertificatePath));

            if (dnsTlsCertificatePassword?.Length > 255)
                throw new ArgumentException("DNS optional protocols TLS certificate password length cannot exceed 255 characters.", nameof(dnsTlsCertificatePassword));

            dnsTlsCertificatePath = ConvertToAbsolutePath(dnsTlsCertificatePath);

            if (throwException)
            {
                LoadDnsTlsCertificate(dnsTlsCertificatePath, dnsTlsCertificatePassword);
            }
            else
            {
                try
                {
                    LoadDnsTlsCertificate(dnsTlsCertificatePath, dnsTlsCertificatePassword);

View on GitHub (pinned to d0484b6c1e)

Solutions

Provide a non-empty absolute or relative path to a .pfx/.p12 file.
Disable DoT/DoH/DoQ protocols if no TLS cert is intended, instead of passing null.
Validate config at startup and surface a friendly message before the call.
Set a sensible default in your configuration template so the field is never null.

Example fix

// before
server.SetDnsTlsCertificate(config.CertPath, config.CertPass);

// after
if (string.IsNullOrWhiteSpace(config.CertPath))
    throw new ConfigurationException("tlsCertificatePath is required when DoT/DoH/DoQ is enabled");
server.SetDnsTlsCertificate(config.CertPath.Trim(), config.CertPass);

Defensive patterns

Strategy: validation

Validate before calling

void EnsureCertPath(string p)
{
    if (string.IsNullOrWhiteSpace(p))
        throw new ConfigurationException("tlsCertificatePath is required");
}

Type guard

static bool IsNonEmptyCertPath(string path) => !string.IsNullOrWhiteSpace(path);

Try / catch

try { server.SetDnsTlsCertificate(path, pass); }
catch (ArgumentNullException ex) when (ex.ParamName == "dnsTlsCertificatePath") { return BadRequest("TLS cert path is required"); }

Prevention

Mark the cert path as required in your config schema.
Disable DoT/DoH/DoQ if no cert is configured.
Default config templates should not allow null here.

When it happens

Trigger: Calling SetDnsTlsCertificate(null, ...) or SetDnsTlsCertificate("", ...). Common when config deserialization yields a missing field, a UI submit sends no path, or a default value is unset.

Common situations: Configuration JSON missing the tlsCertificatePath key; environment variable not set in Docker; first-time setup where DoT/DoH/DoQ is enabled but no cert path supplied; programmatic integration forgetting to set the path.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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