AdguardTeam/AdGuardHome · error

starting dnssvc: %w

Error message

starting dnssvc: %w

What it means

Failed to start the DNS server component during service start; joined with any web-start error via errors.Join.

Source

Thrown at internal/next/cmd/service.go:76

var _ service.Interface = (*serviceMgr)(nil)

// Start implements the [service.Interface] interface for *serviceMgr.
func (s *serviceMgr) Start(ctx context.Context) (err error) {
	s.writePID(ctx)

	s.confMgrMu.RLock()
	defer s.confMgrMu.RUnlock()

	var errs []error

	err = s.confMgr.Web().Start(ctx)
	if err != nil {
		errs = append(errs, fmt.Errorf("starting web: %w", err))
	}

	err = s.confMgr.DNS().Start(ctx)
	if err != nil {
		errs = append(errs, fmt.Errorf("starting dnssvc: %w", err))
	}

	return errors.Join(errs...)
}

// writePID writes the PID to the file.  Any errors are reported to log.
func (s *serviceMgr) writePID(ctx context.Context) {
	if s.pidFilePath == "" {
		return
	}

	pid := os.Getpid()
	data := strconv.AppendInt(nil, int64(pid), 10)
	data = append(data, '\n')

	err := maybe.WriteFile(s.pidFilePath, data, 0o644)
	if err != nil {
		s.logger.ErrorContext(ctx, "writing pidfile", slogutil.KeyError, err)

View on GitHub (pinned to b41aefbe51)

Solutions

1. Stop competing resolvers (systemctl disable --now systemd-resolved or disable stub listener)
2. Run with CAP_NET_BIND_SERVICE or as root for port 53
3. Use a non-privileged dns bind_port for testing

Example fix

# before
# systemd-resolved holds :53
# after
sudo systemctl disable --now systemd-resolved

func dnsPortFree(proto string) bool {
	ln, err := net.Listen(proto, ":53")
	if err != nil { return false }
	_ = ln.Close()
	return true
}

if err := s.Start(ctx); err != nil {
	for _, e := range strings.Split(err.Error(), "\n") {
		if strings.Contains(e, "dnssvc") { log.Printf("DNS start failed: %v", e) }
	}
}

When it happens

Trigger: confMgr.DNS().Start(ctx) errors: UDP/TCP port 53 in use, missing permission to bind a privileged port, or invalid DNS listener config.

Common situations: systemd-resolved/stub or another DNS server occupying :53; running as non-root without CAP_NET_BIND_SERVICE; duplicate listeners after config change.

Related errors

• starting web: %w
• invalid bind_host value: %s
• dns.bind_hosts at index %d is not a valid ip address
• cannot get network interfaces: %w
• collecting dns addresses: %w

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/e83c3c1384a91622. Report an issue: GitHub.