{"record":{"id":"ad72666cd1c0d6f2","repo":"AdguardTeam/AdGuardHome","slug":"preparing-dns-server-w","errorCode":null,"errorMessage":"preparing dns server: %w","messagePattern":"preparing dns server: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/home/dns.go","lineNumber":190,"sourceCode":"\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\n\t// failed to prepare as is.  See TODO on [dnsforward.PrivateRDNSError].\n\terr = globalContext.dnsServer.Prepare(ctx, dnsConf)\n\tif _, ok := errors.AsType[*dnsforward.PrivateRDNSError](err); ok {\n\t\tl := params.Logger\n\t\tl.WarnContext(ctx, \"private rdns resolution failed; disabling\", slogutil.KeyError, err)\n\n\t\tdnsConf.UsePrivateRDNS = false\n\t\terr = globalContext.dnsServer.Prepare(ctx, dnsConf)\n\t}\n\tif err != nil {\n\t\treturn fmt.Errorf(\"preparing dns server: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// parseSubnetSet parses a slice of subnets.  If the slice is empty, it returns\n// a subnet set that matches all locally served networks, see\n// [netutil.IsLocallyServed].\nfunc parseSubnetSet(nets []netutil.Prefix) (s netutil.SubnetSet) {\n\tswitch len(nets) {\n\tcase 0:\n\t\t// Use an optimized function-based matcher.\n\t\treturn netutil.SubnetSetFunc(netutil.IsLocallyServed)\n\tcase 1:\n\t\treturn nets[0].Prefix\n\tdefault:\n\t\treturn netutil.SliceSubnetSet(netutil.UnembedPrefixes(nets))\n\t}","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/home/dns.go#L172-L208","documentation":"dnsforward.Server.Prepare validates the prepared ServerConfig and gets the server ready to listen; this error means the final Prepare call failed even after the automatic retry with private reverse-DNS resolution disabled. Typical causes are invalid upstream configuration or listener address problems surfaced at prepare time.","triggerScenarios":"Calling dnsServer.Prepare(ctx, dnsConf) failing twice: once as-is, once with UsePrivateRDNS=false (the retry only happens when the error is a *dnsforward.PrivateRDNSError). Underlying failures include unreachable/invalid upstream servers and bind-address problems.","commonSituations":"Upstream DNS servers unreachable or misconfigured (bad DoH/DoT URLs), private-RDNS enabled in an environment lacking reverse resolvers, or listen addresses that cannot be prepared on this host.","solutions":["Check the wrapped error: upstream errors usually name the exact server URL that failed","Fix or remove failing upstreams from config.yaml dns section and reload","If the error mentions private RDNS, disable 'Use private reverse DNS resolvers' in settings","Verify listen addresses/interfaces and free any occupied DNS ports"],"exampleFix":"# before\ndns:\n  enable_reverse_mapping: true\n  private_reverse_dns_servers:\n    - 192.168.1.1\n# after — drop unreachable private resolvers or disable reverse mapping\ndns:\n  enable_reverse_mapping: false","handlingStrategy":"fallback","validationCode":"// probe upstreams before Prepare\nfunc upstreamAlive(addr string) bool {\n    r := net.Resolver{}\n    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)\n    defer cancel()\n    _, err := r.LookupHost(ctx, \"example.com\")\n    _ = addr\n    return err == nil\n}","typeGuard":null,"tryCatchPattern":"err = dnsServer.Prepare(ctx, dnsConf)\nif _, ok := errors.AsType[*dnsforward.PrivateRDNSError](err); ok {\n    dnsConf.UsePrivateRDNS = false\n    err = dnsServer.Prepare(ctx, dnsConf) // built-in fallback already retries once\n}\nif err != nil { return fmt.Errorf(\"preparing dns server: %w\", err) }","preventionTips":["Health-check all upstream servers after config changes","Avoid enabling private reverse DNS unless LAN resolvers are reliably up","Keep at least two diverse upstreams so one outage cannot fail Prepare"],"tags":["dns","adguard-home","upstream-connectivity","prepare","server-startup"],"backgroundTag":"upstream-dns-unreachable","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}