AdguardTeam/AdGuardHome · critical

creating new dns server

Error message

creating new dns server: %w

What it means

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.

Solutions

1. Read the wrapped error to identify whether it is config, TLS, or bind related
2. If triggered by a reconfigure, fix or revert the last config change before retrying
3. Resolve port/interface conflicts and confirm TLS key/cert files are readable
4. Restart the service cleanly after fixing; initDNSServer auto-cleans via closeDNSServer

// in cmdlineUpdate paths: keep the last good server on failure
if err := initDNSServer(ctx, params, httpReg, confModifier); err != nil {
    log.Error("reconfigure failed; keeping previous DNS server", slogutil.KeyError, err)
    return err // closeDNSServer already ran via defer
}

When it happens

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

Common situations: Reconfiguration applying a broken config, TLS certificates unreadable at reload time, or the same port-conflict class as initial startup.

Related errors

• creating dns server
• preparing dns server
• constructing tls config
• creating dnscrypt cert
• creating new dns server config

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

Appendix: source

Thrown at internal/home/dns.go:161

// valid.  In other cases all the arguments also must not be nil.  It also must
// not be called unless [config] and [globalContext] are
// initialized.
func initDNSServer(
	ctx context.Context,
	params dnsforward.DNSCreateParams,
	httpReg aghhttp.Registrar,
	confModifier agh.ConfigModifier,
) (err error) {
	globalContext.dnsServer, err = dnsforward.NewServer(params)
	// TODO(m.kazantsev):  Investigate if the server should be closed in case of
	// error and consider removing this defer.
	defer func() {
		if err != nil {
			closeDNSServer(ctx, params.Logger)
		}
	}()
	if err != nil {
		return fmt.Errorf("creating new dns server: %w", err)
	}

	globalContext.clients.clientChecker = globalContext.dnsServer

	dnsConf, err := newServerConfig(
		&config.DNS,
		config.Clients.Sources,
		config.HTTPConfig.DoH,
		params.TLSManager,
		httpReg,
		globalContext.clients.storage,
		confModifier,
	)
	if err != nil {
		return fmt.Errorf("creating new dns server config: %w", err)
	}

	// Try to prepare the server with disabled private RDNS resolution if it

View on GitHub (pinned to b41aefbe51)