AdguardTeam/AdGuardHome · error

unexpected family

Error message

%q %q unexpected family %q

What it means

While iterating sets for a host, addToSets hit the default family branch — the set's family is neither IPv4 nor IPv6. Defensive invariant check mirroring 391 at the addToSets level.

Solutions

1. Restart the service to rebuild the ipset cache
2. Verify all referenced sets have valid families with 'ipset list'
3. Report upstream with logs if persistent

func (p props) hasValidFamily() bool {
	return p.family == netfilter.ProtoIPv4 || p.family == netfilter.ProtoIPv6
}

When it happens

Trigger: A cached props entry with invalid family reaches the add loop, e.g. after a failed re-query left inconsistent state.

Common situations: Extremely rare; indicates corrupted internal state or an upstream parsing bug rather than user misconfiguration.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• unexpected family for ipset
• dialing netfilter
• dialing v4
• dialing v6
• adding to

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

Appendix: source

Thrown at internal/ipset/ipset_linux.go:511

	ip4s []net.IP,
	ip6s []net.IP,
	sets []props,
) (n int, err error) {
	for _, set := range sets {
		var nn int
		switch set.family {
		case netfilter.ProtoIPv4:
			nn, err = m.addIPs(host, set, ip4s)
			if err != nil {
				return n, err
			}
		case netfilter.ProtoIPv6:
			nn, err = m.addIPs(host, set, ip6s)
			if err != nil {
				return n, err
			}
		default:
			return n, fmt.Errorf("%q %q unexpected family %q", set.name, set.typeName, set.family)
		}

		m.logger.DebugContext(
			ctx,
			"added ips to set",
			"ips_num", nn,
			"set_name", set.name,
			"set_type", set.typeName,
		)

		n += nn
	}

	return n, nil
}

// Add implements the [Manager] interface for *manager.
func (m *manager) Add(ctx context.Context, host string, ip4s, ip6s []net.IP) (n int, err error) {

View on GitHub (pinned to b41aefbe51)