{"record":{"id":"f679203a3b2b863c","repo":"AdguardTeam/AdGuardHome","slug":"creating-new-dns-server-w","errorCode":null,"errorMessage":"creating new dns server: %w","messagePattern":"creating new dns server: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/home/dns.go","lineNumber":161,"sourceCode":"// valid.  In other cases all the arguments also must not be nil.  It also must\n// not be called unless [config] and [globalContext] are\n// initialized.\nfunc initDNSServer(\n\tctx context.Context,\n\tparams dnsforward.DNSCreateParams,\n\thttpReg aghhttp.Registrar,\n\tconfModifier agh.ConfigModifier,\n) (err error) {\n\tglobalContext.dnsServer, err = dnsforward.NewServer(params)\n\t// TODO(m.kazantsev):  Investigate if the server should be closed in case of\n\t// error and consider removing this defer.\n\tdefer func() {\n\t\tif err != nil {\n\t\t\tcloseDNSServer(ctx, params.Logger)\n\t\t}\n\t}()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"creating new dns server: %w\", err)\n\t}\n\n\tglobalContext.clients.clientChecker = globalContext.dnsServer\n\n\tdnsConf, err := newServerConfig(\n\t\t&config.DNS,\n\t\tconfig.Clients.Sources,\n\t\tconfig.HTTPConfig.DoH,\n\t\tparams.TLSManager,\n\t\thttpReg,\n\t\tglobalContext.clients.storage,\n\t\tconfModifier,\n\t)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"creating new dns server config: %w\", err)\n\t}\n\n\t// Try to prepare the server with disabled private RDNS resolution if it","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/home/dns.go#L143-L179","documentation":"Identical failure class as error 311 but raised inside initDNSServer, the helper that (re)creates the dnsforward server — used both at startup and by runtime reconfiguration (cmdlineUpdate). The dnsServerNew call failed; on error the deferred closeDNSServer cleans up the partially created server.","triggerScenarios":"dnsServerNew returning an error during initial start or during a runtime reconfigure via cmdlineUpdate — invalid params, TLS manager registration failure, or client-storage wiring problems.","commonSituations":"Reconfiguration applying a broken config, TLS certificates unreadable at reload time, or the same port-conflict class as initial startup.","solutions":["Read the wrapped error to identify whether it is config, TLS, or bind related","If triggered by a reconfigure, fix or revert the last config change before retrying","Resolve port/interface conflicts and confirm TLS key/cert files are readable","Restart the service cleanly after fixing; initDNSServer auto-cleans via closeDNSServer"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// in cmdlineUpdate paths: keep the last good server on failure\nif err := initDNSServer(ctx, params, httpReg, confModifier); err != nil {\n    log.Error(\"reconfigure failed; keeping previous DNS server\", slogutil.KeyError, err)\n    return err // closeDNSServer already ran via defer\n}","preventionTips":["Validate new config before applying it at runtime (dry-run)","Keep TLS cert paths stable and readable across restarts","Wrap runtime reconfigurations so a failed Prepare falls back to the running config"],"tags":["dns","adguard-home","server-startup","reconfiguration"],"backgroundTag":"server-init-failed","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}