What causes "cannot start DNS server: %w" in lima-vm/lima?

Check for a conflicting listener on the resolver port (lsof -i :53 or the configured port) and stop it, or change hostResolver related ports

lima-vm/lima · error

cannot start DNS server: %w

Error message

cannot start DNS server: %w

What it means

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.

Source

Thrown at pkg/hostagent/hostagent.go:430

		hosts := a.instConfig.HostResolver.Hosts
		if hosts == nil {
			hosts = make(map[string]string)
		}
		hosts["host.lima.internal"] = networks.SlirpGateway
		name := hostname.FromInstName(a.instName) // TODO: support customization
		hosts[name] = networks.SlirpIPAddress
		srvOpts := dns.ServerOptions{
			UDPPort: a.udpDNSLocalPort,
			TCPPort: a.tcpDNSLocalPort,
			Address: "127.0.0.1",
			HandlerOptions: dns.HandlerOptions{
				IPv6:        *a.instConfig.HostResolver.IPv6,
				StaticHosts: hosts,
			},
		}
		dnsServer, err := dns.Start(srvOpts)
		if err != nil {
			return fmt.Errorf("cannot start DNS server: %w", err)
		}
		defer dnsServer.Shutdown()
	}

	errCh, err := a.driver.Start(ctx)
	if err != nil {
		return err
	}

	if err := a.driver.AdditionalSetupForSSH(ctx); err != nil {
		return err
	}

	// WSL instance SSH address isn't known until after VM start
	if a.driver.Info(ctx).Features.DynamicSSHAddress {
		sshAddr, err := a.driver.SSHAddress(ctx)
		if err != nil {
			return err

View on GitHub (pinned to dd909d0973)

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

Example fix

// before (lima.yaml)
hostResolver:
  ipv6: true   # host has no IPv6
// after
hostResolver:
  ipv6: false

Defensive patterns

Strategy: validation

Validate before calling

// check the resolver port is bindable before starting
addr := "127.0.0.1:53" // or your configured resolver addr
probe, err := net.ListenPacket("udp", addr)
if err != nil {
	return fmt.Errorf("DNS port %s in use or blocked: %w", addr, err)
}
probe.Close()

Try / catch

if strings.Contains(err.Error(), "cannot start DNS server") {
	// degrade gracefully: disable host resolver and retry
	inst.Config.HostResolver.Enabled = pointer.Bool(false)
	return restartInstance(ctx, inst)
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/3cceac7c1321c48d. Report an issue: GitHub.