AdguardTeam/AdGuardHome · error

%v is not an IPv4 %s

Error message

%v is not an IPv4 %s

What it means

ensureV4 verifies that an address used in DHCPv4 configuration is a valid IPv4 address. The address is either invalid (zero), IPv6, or an IPv4-in-IPv6 mapped address that unmapped to something non-IPv4. 'kind' names the field (e.g. gateway, range start).

Source

Thrown at internal/dhcpd/config.go:162

	// notify is a way to signal to other components that leases have been
	// changed.  notify must be called outside of locked sections, since the
	// clients might want to get the new data.
	//
	// TODO(a.garipov): This is utter madness and must be refactored.  It just
	// begs for deadlock bugs and other nastiness.
	notify func(uint32)
}

// errNilConfig is an error returned by validation method if the config is nil.
const errNilConfig errors.Error = "nil config"

// ensureV4 returns an unmapped version of ip.  An error is returned if the
// passed ip is not an IPv4.
func ensureV4(ip netip.Addr, kind string) (ip4 netip.Addr, err error) {
	ip4 = ip.Unmap()
	if !ip4.IsValid() || !ip4.Is4() {
		return netip.Addr{}, fmt.Errorf("%v is not an IPv4 %s", ip, kind)
	}

	return ip4, nil
}

// Validate returns an error if c is not a valid configuration.
//
// TODO(e.burkov):  Don't set the config fields when the server itself will stop
// containing the config.
func (c *V4ServerConf) Validate() (err error) {
	defer func() { err = errors.Annotate(err, "dhcpv4: %w") }()

	if c == nil {
		return errNilConfig
	}

	gatewayIP, err := ensureV4(c.GatewayIP, "address")
	if err != nil {

View on GitHub (pinned to b41aefbe51)

Solutions

1. Correct the offending field to a valid dotted-quad IPv4 address
2. Ensure RangeStart/RangeEnd/gateway are set (not empty) before enabling DHCPv4
3. If addresses come from parsing, check parse errors before Validate

Example fix

// before
cfg.GatewayIP = netip.MustParseAddr("fe80::1")
// after
cfg.GatewayIP = netip.MustParseAddr("192.168.1.1")

// before Validate/Create
for _, ip := range []netip.Addr{cfg.RangeStart, cfg.RangeEnd, gatewayIP} {
    if !ip.IsValid() || !ip.Is4() { return errors.New("need valid IPv4") }
}

func isIPv4(a netip.Addr) bool { a = a.Unmap(); return a.IsValid() && a.Is4() }

When it happens

Trigger: Calling Validate on DHCPv4 config where RangeStart, RangeEnd, or gateway is an IPv6 address or an unparseable/zero netip.Addr (e.g. a typo like 192.168.1.256 or an address left unset as netip.Addr{}).

Common situations: UI or API input of an IPv6 address into an IPv4 field, forgetting to set the gateway, or parsing failures upstream that yield invalid Addr values.

Related errors

• neither dhcpv4 nor dhcpv6 srv is configured
• creating dhcpv4 srv: %w
• parsing ip at index %d: %w
• subnet %s does not contain the ip %q
• lease %s (%s) out of range, not adding

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