{"record":{"id":"02150a643ea37993","repo":"AdguardTeam/AdGuardHome","slug":"constructing-tls-config-w","errorCode":null,"errorMessage":"constructing tls config: %w","messagePattern":"constructing tls config: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/home/dns.go","lineNumber":275,"sourceCode":"// newServerConfig converts values from the configuration file into the internal\n// DNS server configuration.  All arguments must not be nil.\nfunc newServerConfig(\n\tdnsConf *dnsConfig,\n\tclientSrcConf *clientSourcesConfig,\n\tdohConf *doHConfig,\n\ttlsManager aghtls.Manager,\n\thttpReg aghhttp.Registrar,\n\tclientsContainer dnsforward.ClientsContainer,\n\tconfModifier agh.ConfigModifier,\n) (newConf *dnsforward.ServerConfig, err error) {\n\thosts := aghalg.CoalesceSlice(dnsConf.BindHosts, []netip.Addr{netutil.IPv4Localhost()})\n\n\tfwdConf := dnsConf.Config\n\tfwdConf.ClientsContainer = clientsContainer\n\n\tintTLSConf, err := newDNSTLSConfig(tlsManager, hosts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"constructing tls config: %w\", err)\n\t}\n\n\tnewConf = &dnsforward.ServerConfig{\n\t\tUDPListenAddrs:         ipsToUDPAddrs(hosts, dnsConf.Port),\n\t\tTCPListenAddrs:         ipsToTCPAddrs(hosts, dnsConf.Port),\n\t\tConfig:                 fwdConf,\n\t\tTLSConf:                intTLSConf,\n\t\tTLSAllowUnencryptedDoH: dohConf.InsecureEnabled,\n\t\tUpstreamTimeout:        time.Duration(dnsConf.UpstreamTimeout),\n\t\tConfModifier:           confModifier,\n\t\tHTTPReg:                httpReg,\n\t\tLocalPTRResolvers:      dnsConf.PrivateRDNSResolvers,\n\t\tUseDNS64:               dnsConf.UseDNS64,\n\t\tDNS64Prefixes:          dnsConf.DNS64Prefixes,\n\t\tUsePrivateRDNS:         dnsConf.UsePrivateRDNS,\n\t\tServeHTTP3:             dnsConf.ServeHTTP3,\n\t\tUseHTTP3Upstreams:      dnsConf.UseHTTP3Upstreams,\n\t\tServePlainDNS:          dnsConf.ServePlainDNS,","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/home/dns.go#L257-L293","documentation":"newServerConfig could not build the TLS configuration for the DNS server. newDNSTLSConfig combines certificate data for DNS-over-TLS/HTTPS/QUIC plus optional DNSCrypt settings; failure means certificates are missing/invalid or the DNSCrypt sub-configuration failed.","triggerScenarios":"Enabling DoT/DoH/DoQ with invalid, missing, or unreadable certificate files (certificate chain, private key), expired/unparseable PEM data, or a DNSCrypt config error surfacing through newDNSTLSConfig.","commonSituations":"paths in tls config pointing to moved/deleted cert files, cert and key mismatched, cert expired after Let's Encrypt renewal script failed, or wrong file permissions.","solutions":["Verify certificate_chain and private_key paths exist and are readable by the service user","Validate the pair matches: openssl x509 -noout -modulus -in cert.pem | openssl md5 vs openssl rsa -noout -modulus -in key.pem | openssl md5","Renew or re-issue the certificate if expired or corrupt","If DNSCrypt is enabled, check the wrapped error for the DNSCryptConfig sub-error and fix that file first"],"exampleFix":"# check cert validity\nopenssl x509 -in cert.pem -noout -dates -subject\n# regenerate self-signed pair if broken\nopenssl req -x509 -newkey rsa:2048 -sha256 -days 365 -nodes \\\n  -keyout key.pem -out cert.pem -subj '/CN=dns.example.com'","handlingStrategy":"validation","validationCode":"// pre-validate TLS material before enabling DoT/DoH/DoQ\nfunc certPairOK(certPath, keyPath string) error {\n    cb, err := os.ReadFile(certPath); if err != nil { return err }\n    kb, err := os.ReadFile(keyPath); if err != nil { return err }\n    c, _ := tls.X509KeyPair(cb, kb)\n    if c.Certificate == nil { return fmt.Errorf(\"cert/key mismatch or unparseable\") }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if _, err := newDNSTLSConfig(tlsManager, hosts); err != nil {\n    return nil, fmt.Errorf(\"constructing tls config: %w\", err) // inspect for cert vs dnscrypt cause\n}","preventionTips":["Automate certificate renewal (acme/letsencrypt) with reload hooks","Test key/cert pairs with tls.X509KeyPair in CI for checked-in configs","Monitor certificate expiry so renewal failures surface before restart"],"tags":["dns","adguard-home","tls","certificates","configuration"],"backgroundTag":"tls-certificate-invalid","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}