TechnitiumSoftware/DnsServer · warning · ArgumentException

DNS optional protocols TLS certificate path length cannot ex

Error message

DNS optional protocols TLS certificate path length cannot exceed 255 characters.

What it means

Thrown by SetDnsTlsCertificate when dnsTlsCertificatePath.Length exceeds 255. The cap matches filesystem/path limits and the server's config serialization budget; longer paths are rejected before filesystem access.

Source

Thrown at DnsServerCore/Dns/DnsServer.cs:1643

        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);
                }
                catch (Exception ex)
                {

View on GitHub (pinned to d0484b6c1e)

Solutions

Shorten the path: place the cert in a shallow directory like /etc/dns/cert.pfx or C:\certs\dns.pfx.
Use a relative path if your working directory is near the file.
Symlink a short path to the long real location.
Trim accidental whitespace or duplicated separators before measuring length.

Example fix

# before
/var/lib/technitium-dns/server/data/apps/acme-issuer/store/2024/01/fullchain-bundled-3a9f8c.pfx

# after
ln -s /var/lib/.../3a9f8c.pfx /etc/dns/cert.pfx
server.SetDnsTlsCertificate("/etc/dns/cert.pfx", pw);

Defensive patterns

Strategy: validation

Validate before calling

string ShortenCertPath(string p)
{
    var full = Path.GetFullPath(p);
    if (full.Length > 255) throw new ConfigurationException($"Cert path too long ({full.Length}): use a shallower directory or a symlink");
    return full;
}

Type guard

static bool IsCertPathWithinLength(string path) => (path?.Length ?? 0) <= 255;

Try / catch

try { server.SetDnsTlsCertificate(path, pass); }
catch (ArgumentException ex) when (ex.Message.Contains("path length cannot exceed")) { return BadRequest("Use a shorter certificate path"); }

Prevention

Place certs in a shallow directory (/etc/dns/cert.pfx).
Use a symlink if the real path is long.
Validate path length before submission.

When it happens

Trigger: Passing a deeply nested absolute path or a path with many segments such that total length > 255 characters.

Common situations: Long Windows drive paths (C:\Users\...\very\deep\folder\certificate.pfx); embedded base64 or hash in the filename; container overlayfs paths; misconfigured variable concatenation producing a long string.

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/94439920edd34537. Report an issue: GitHub.