AdguardTeam/AdGuardHome · critical

dns.bind_hosts at index %d is not a valid ip address

Error message

dns.bind_hosts at index %d is not a valid ip address

What it means

Config validation found an entry in dns.bind_hosts that is not a valid IP address (invalid netip.Addr). The index of the offending entry is included.

Source

Thrown at internal/home/config.go:642

}

// validateBindHosts returns error if any of binding hosts from configuration is
// not a valid IP address.
func validateBindHosts(
	ctx context.Context,
	l *slog.Logger,
	conf *configuration,
	fileData []byte,
) (err error) {
	if !conf.HTTPConfig.Address.IsValid() {
		return errors.Error("http.address is not a valid ip address")
	}

	for i, addr := range conf.DNS.BindHosts {
		if !addr.IsValid() {
			logIPHint(ctx, l, fileData)

			return fmt.Errorf("dns.bind_hosts at index %d is not a valid ip address", i)
		}
	}

	return nil
}

// parseConfig loads configuration from the YAML file, upgrading it if
// necessary.  l must not be nil.
func parseConfig(ctx context.Context, l *slog.Logger, workDir, confPath string) (err error) {
	// Do the upgrade if necessary.
	config.fileData, err = readConfigFile(ctx, l, workDir, confPath)
	if err != nil {
		return err
	}

	migrator := configmigrate.New(&configmigrate.Config{
		Logger:     l.With(slogutil.KeyPrefix, "config_migrator"),
		WorkingDir: workDir,

View on GitHub (pinned to b41aefbe51)

Solutions

1. Open AdGuardHome.yaml and fix/remove the dns.bind_hosts entry at the reported index — use bare IP literals like 0.0.0.0 or 127.0.0.1
2. Replace hostnames with the IPs they resolve to
3. Validate the YAML with a linter before restarting

Example fix

# before
dns:
  bind_hosts:
    - localhost
# after
dns:
  bind_hosts:
    - 127.0.0.1

// Validate bind hosts before deploy
for _, h := range cfg.DNS.BindHosts {
    if netip.MustParseAddr(h).String() != h { return errors.New("invalid ip") }
}

func validBindHosts(hosts []string) bool {
    for _, h := range hosts {
        if _, err := netip.ParseAddr(h); err != nil { return false }
    }
    return true
}

When it happens

Trigger: YAML config containing bind_hosts entries that are empty strings, hostnames, or malformed IPs (e.g. "192.168.1", "localhost").

Common situations: Hand-edited AdGuardHome.yaml, using a hostname or CIDR where a bare IP is required, trailing spaces/quotes mistakes, migration from older config formats.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• writing conf: %w
• invalid upstream servers: %w
• validating tcp ports: %w
• validating udp ports: %w
• json time is nil

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