AdguardTeam/AdGuardHome · error

another client %q uses the same subnet %q

Error message

another client %q uses the same subnet %q

What it means

Thrown when the client's subnet (/24 or configured subnet range) overlaps with another client's subnet in the index. AdGuard Home requires persistent clients to map to disjoint subnet ranges. The error names the conflicting client and subnet.

Source

Thrown at internal/client/index.go:128

	}

	for _, id := range c.ClientIDs {
		existing, ok := ci.clientIDToUID[id]
		if ok && existing != c.UID {
			p := ci.uidToClient[existing]

			return fmt.Errorf("another client %q uses the same ClientID %q", p.Name, id)
		}
	}

	p, ip := ci.clashesIP(c)
	if p != nil {
		return fmt.Errorf("another client %q uses the same IP %q", p.Name, ip)
	}

	p, s := ci.clashesSubnet(c)
	if p != nil {
		return fmt.Errorf("another client %q uses the same subnet %q", p.Name, s)
	}

	p, mac := ci.clashesMAC(c)
	if p != nil {
		return fmt.Errorf("another client %q uses the same MAC %q", p.Name, mac)
	}

	return nil
}

// clashesName returns existing persistent client with the same name as c or
// nil.  c must be non-nil.
func (ci *index) clashesName(c *Persistent) (existing *Persistent) {
	existing, ok := ci.findByName(c.Name)
	if !ok {
		return nil
	}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check the client named in the message and either disable one client's subnet identification or move the clients into distinct subnets
2. Use exact IP or ClientID identification instead of subnet identification for dense networks
3. Use Update on the existing client instead of adding a second one covering the same subnet

Example fix

// before
client.UseSubnets = true; client.IP = "10.0.0.5"  // "10.0.0.0/24" already claimed
s.Add(ctx, client)

// after
client.UseSubnets = false
s.Add(ctx, client)

func subnetClash(p, c client.Persistent) bool {
    return p.UseSubnets && c.UseSubnets && p.IP.As4()[0:3] == c.IP.As4()[0:3] // /24 heuristic
}

if err := s.Update(ctx, name, c); err != nil && strings.Contains(err.Error(), "uses the same subnet") { c.UseSubnets = false; _ = s.Update(ctx, name, c) }

When it happens

Trigger: Calling Storage.Add or Storage.Update with a client whose subnet (derived from its IP) matches the subnet of a different stored client, as detected by clashesSubnet.

Common situations: Defining multiple clients inside the same /24 when subnet-based identification is enabled, migrating configs where subnet clients were keyed by broader ranges.

Related errors

• another client %q uses the same ClientID %q
• another client %q uses the same IP %q
• another client %q uses the same MAC %q
• invalid upstream servers: %w
• invalid tag: %q

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