TechnitiumSoftware/DnsServer · error · ArgumentException

Web service TLS certificate path length cannot exceed 255 ch

Error message

Web service TLS certificate path length cannot exceed 255 characters.

What it means

ArgumentException thrown by SetWebServiceTlsCertificate when webServiceTlsCertificatePath.Length exceeds 255 characters. The limit exists because the path is later persisted into the binary config (single-byte length prefix) and stored relative; longer paths would corrupt the config layout.

Source

Thrown at DnsServerCore/DnsWebService.cs:2749

        }

        private void RemoveWebServiceTlsCertificate()
        {
            _webServiceSslServerAuthenticationOptions = null;

            _webServiceTlsCertificatePath = null;
            _webServiceTlsCertificatePassword = null;

            StopTlsCertificateUpdateTimer();
        }

        public void SetWebServiceTlsCertificate(string webServiceTlsCertificatePath, string webServiceTlsCertificatePassword)
        {
            if (string.IsNullOrWhiteSpace(webServiceTlsCertificatePath))
                throw new ArgumentException("Web service TLS certificate path cannot be null or empty.", nameof(webServiceTlsCertificatePath));

            if (webServiceTlsCertificatePath.Length > 255)
                throw new ArgumentException("Web service TLS certificate path length cannot exceed 255 characters.", nameof(webServiceTlsCertificatePath));

            if (webServiceTlsCertificatePassword?.Length > 255)
                throw new ArgumentException("Web service TLS certificate password length cannot exceed 255 characters.", nameof(webServiceTlsCertificatePassword));

            webServiceTlsCertificatePath = ConvertToAbsolutePath(webServiceTlsCertificatePath);

            LoadWebServiceTlsCertificate(webServiceTlsCertificatePath, webServiceTlsCertificatePassword);

            _webServiceTlsCertificatePath = ConvertToRelativePath(webServiceTlsCertificatePath);
            _webServiceTlsCertificatePassword = webServiceTlsCertificatePassword;

            StartTlsCertificateUpdateTimer();
        }

        private void CheckAndLoadSelfSignedCertificate(bool forceGenerateNew, bool throwException)
        {
            string selfSignedCertificateFilePath = Path.Combine(_configFolder, "self-signed-cert.pfx");

View on GitHub (pinned to d0484b6c1e)

Solutions

Move the certificate file closer to the root / config folder so the (relative) path stays under 255 chars.
Use a shorter directory name or reorganize the cert store layout.
On Windows, enable long paths and/or shorten the working directory the relative path is computed from.

Example fix

null

Defensive patterns

Strategy: validation

Validate before calling

if (webServiceTlsCertificatePath.Length > 255)
    throw new ArgumentException("TLS certificate path must be <= 255 characters.");

Type guard

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

Try / catch

null

Prevention

Keep certificate paths short and close to the config root.
Avoid deeply nested or container overlay paths for certificates.
Use relative paths from the service working directory where possible.

When it happens

Trigger: Calling SetWebServiceTlsCertificate with a path longer than 255 characters, e.g. a deeply nested absolute path or a long container/mount path.

Common situations: Windows long paths; deep container overlay paths; certificate stored far down a directory tree; very long volume mount prefixes.

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