TechnitiumSoftware/DnsServer · error · ArgumentException

Web server '{_name}' TLS certificate file must be PKCS #12 f

Error message

Web server '{_name}' TLS certificate file must be PKCS #12 formatted with .pfx or .p12 extension: {webServerTlsCertificateFilePath}

What it means

Thrown by BlockPageApp LoadWebServiceTlsCertificate when the TLS certificate file exists but its extension is neither .pfx nor .p12. The loader only supports PKCS #12 bundles, so any other format (e.g. .crt, .pem, .cer, .key) raises ArgumentException.

Source

Thrown at Apps/BlockPageApp/App.cs:478

                    _webServer = null;
                }
            }

            private void LoadWebServiceTlsCertificate(string webServerTlsCertificateFilePath, string? webServerTlsCertificatePassword)
            {
                FileInfo fileInfo = new FileInfo(webServerTlsCertificateFilePath);

                if (!fileInfo.Exists)
                    throw new ArgumentException("Web server '" + _name + "' TLS certificate file does not exists: " + webServerTlsCertificateFilePath);

                switch (Path.GetExtension(webServerTlsCertificateFilePath).ToLowerInvariant())
                {
                    case ".pfx":
                    case ".p12":
                        break;

                    default:
                        throw new ArgumentException("Web server '" + _name + "' TLS certificate file must be PKCS #12 formatted with .pfx or .p12 extension: " + webServerTlsCertificateFilePath);
                }

                X509Certificate2Collection webServerTlsCertificateCollection = X509CertificateLoader.LoadPkcs12CollectionFromFile(webServerTlsCertificateFilePath, webServerTlsCertificatePassword, X509KeyStorageFlags.PersistKeySet);
                X509Certificate2? serverCertificate = null;

                foreach (X509Certificate2 certificate in webServerTlsCertificateCollection)
                {
                    if (certificate.HasPrivateKey)
                    {
                        serverCertificate = certificate;
                        break;
                    }
                }

                if (serverCertificate is null)
                    throw new ArgumentException("Web server '" + _name + "' TLS certificate file must contain a certificate with private key.");

                _sslServerAuthenticationOptions = new SslServerAuthenticationOptions()

View on GitHub (pinned to d0484b6c1e)

Solutions

Convert the certificate and its private key into a PKCS #12 bundle: 'openssl pkcs12 -export -out server.pfx -inkey server.key -in server.crt'.
Point 'webServerTlsCertificateFilePath' at the resulting .pfx (or .p12) file.
Make sure the .pfx includes the private key and use the matching password.

Example fix

# convert PEM cert+key to PKCS#12
openssl pkcs12 -export -out blockpage.pfx -inkey privkey.pem -in fullchain.pem
# then in dnsApp.config
"webServerTlsCertificateFilePath": "blockpage.pfx"

Defensive patterns

Strategy: type-guard

Validate before calling

string ext = Path.GetExtension(webServerTlsCertificateFilePath).ToLowerInvariant();
if (ext != ".pfx" && ext != ".p12")
    throw new FormatException($"TLS certificate must be PKCS #12 (.pfx/.p12); got '{ext}'. Convert with: openssl pkcs12 -export -out server.pfx -inkey server.key -in server.crt");

Type guard

static bool IsPkcs12File(string path)
{
    string ext = Path.GetExtension(path).ToLowerInvariant();
    return ext == ".pfx" || ext == ".p12";
}

Prevention

Export certificates as PKCS #12 bundles including the private key.
Use the .pfx or .p12 extension consistently.
Convert PEM/DER with OpenSSL before referencing in config.

When it happens

Trigger: Configuring 'webServerTlsCertificateFilePath' to a PEM, DER, CRT, or CER file instead of a PKCS #12 (.pfx/.p12) bundle.

Common situations: Exporting only the public cert (.crt) or a PEM chain from a CA and pointing the config at it; using a Letsencrypt live file directly without conversion to PFX.

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