AdguardTeam/AdGuardHome · critical

creating new dns server: %w

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.

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)

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: %w
• preparing dns server: %w
• init querylog: %w
• creating new dns server config: %w
• constructing tls config: %w

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