AdguardTeam/AdGuardHome · error

another client %q uses the same IP %q

Error message

another client %q uses the same IP %q

What it means

Thrown when a new or updated client's IP address collides with another client's IP in the storage index. Each persistent client must have a unique IP. The error reports the existing client's name and the clashing IP.

Source

Thrown at internal/client/index.go:123

// clashes returns an error if the index contains a different persistent client
// with at least a single identifier contained by c.  c must be non-nil.
func (ci *index) clashes(c *Persistent) (err error) {
	if p := ci.clashesName(c); p != nil {
		return fmt.Errorf("another client uses the same name %q", p.Name)
	}

	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) {

View on GitHub (pinned to b41aefbe51)

Solutions

  1. Find the client named in the message and change one of the two IPs to a free address
  2. If the same device is being re-added, use Update on the existing client by name instead of Add
  3. Validate IPs for uniqueness before loading InitialClients into NewStorage

Example fix

// before
client.IP = "192.168.1.10" // already used by "printer"
s.Add(ctx, client)

// after
client.IP = "192.168.1.42"
s.Add(ctx, client)
Defensive patterns

Strategy: validation

Validate before calling

for _, p := range existing {
    if p.UID != c.UID && p.IP == c.IP { /* clash */ }
}

Try / catch

if err := s.Add(ctx, c); err != nil && strings.Contains(err.Error(), "uses the same IP") { /* reassign IP or Update */ }

Prevention

When it happens

Trigger: Calling Storage.Add or Storage.Update with a client whose IP (or whose IP is matched by clashesIP) equals the IP of a different already-stored client.

Common situations: Static-IP client lists where two devices were assigned the same address, DHCP reservations duplicated across clients, importing YAML configs with copy-pasted IP fields.

Related errors

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