{"record":{"id":"3cceac7c1321c48d","repo":"lima-vm/lima","slug":"cannot-start-dns-server-w","errorCode":null,"errorMessage":"cannot start DNS server: %w","messagePattern":"cannot start DNS server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/hostagent/hostagent.go","lineNumber":430,"sourceCode":"\t\thosts := a.instConfig.HostResolver.Hosts\n\t\tif hosts == nil {\n\t\t\thosts = make(map[string]string)\n\t\t}\n\t\thosts[\"host.lima.internal\"] = networks.SlirpGateway\n\t\tname := hostname.FromInstName(a.instName) // TODO: support customization\n\t\thosts[name] = networks.SlirpIPAddress\n\t\tsrvOpts := dns.ServerOptions{\n\t\t\tUDPPort: a.udpDNSLocalPort,\n\t\t\tTCPPort: a.tcpDNSLocalPort,\n\t\t\tAddress: \"127.0.0.1\",\n\t\t\tHandlerOptions: dns.HandlerOptions{\n\t\t\t\tIPv6:        *a.instConfig.HostResolver.IPv6,\n\t\t\t\tStaticHosts: hosts,\n\t\t\t},\n\t\t}\n\t\tdnsServer, err := dns.Start(srvOpts)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"cannot start DNS server: %w\", err)\n\t\t}\n\t\tdefer dnsServer.Shutdown()\n\t}\n\n\terrCh, err := a.driver.Start(ctx)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif err := a.driver.AdditionalSetupForSSH(ctx); err != nil {\n\t\treturn err\n\t}\n\n\t// WSL instance SSH address isn't known until after VM start\n\tif a.driver.Info(ctx).Features.DynamicSSHAddress {\n\t\tsshAddr, err := a.driver.SSHAddress(ctx)\n\t\tif err != nil {\n\t\t\treturn err","sourceCodeStart":412,"sourceCodeEnd":448,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/hostagent/hostagent.go#L412-L448","documentation":"In HostAgent.Run, when the instance config enables hostResolver, Lima starts an embedded DNS server (dns.Start) with the resolver options. If the server cannot start, Run returns this wrapped error and the hostagent aborts.","triggerScenarios":"hostagent.Run on an instance with hostResolver.enabled: true where dns.Start fails — most commonly because the UDP listen address/port is already in use or the requested IP mode (IPv4/IPv6) is unavailable on the host.","commonSituations":"Port conflict: another process (or a second Lima instance with a pinned resolver port) already bound to the DNS port; IPv6 disabled on the host while hostResolver.ipv6 is true; sandbox lacking permission to bind.","solutions":["Check for a conflicting listener on the resolver port (lsof -i :53 or the configured port) and stop it, or change hostResolver related ports","If your host lacks IPv6, set hostResolver.ipv6: false in the instance config","Disable the host resolver entirely (hostResolver.enabled: false) if you don't need custom hosts/IPv6","Inspect the wrapped underlying error for the specific bind/OS failure"],"exampleFix":"// before (lima.yaml)\nhostResolver:\n  ipv6: true   # host has no IPv6\n// after\nhostResolver:\n  ipv6: false","handlingStrategy":"validation","validationCode":"// check the resolver port is bindable before starting\naddr := \"127.0.0.1:53\" // or your configured resolver addr\nprobe, err := net.ListenPacket(\"udp\", addr)\nif err != nil {\n\treturn fmt.Errorf(\"DNS port %s in use or blocked: %w\", addr, err)\n}\nprobe.Close()","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"cannot start DNS server\") {\n\t// degrade gracefully: disable host resolver and retry\n\tinst.Config.HostResolver.Enabled = pointer.Bool(false)\n\treturn restartInstance(ctx, inst)\n}","preventionTips":["Verify IPv6 availability on the host before enabling hostResolver.ipv6","Check port conflicts (lsof -i :53) when running other DNS software","Disable hostResolver if you don't need custom hosts entries","Run one Lima hostagent per host or use distinct resolver ports"],"tags":["dns","network","resolver","bind"],"backgroundTag":"dns-server-start-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}