AdguardTeam/AdGuardHome · error

client at index %d: %w

Error message

client at index %d: %w

What it means

While migrating clients to schema v6, reading the 'ip' or 'mac' field of a client returned an error from the generic fieldVal helper, typically because the field exists but is not a string (e.g. it is a number, list, or null map type mismatch).

Source

Thrown at internal/configmigrate/v6.go:49

	diskConf["schema_version"] = 6

	clients, ok, err := fieldVal[yarr](diskConf, "clients")
	if !ok {
		return err
	}

	for i, client := range clients {
		var c yobj
		c, ok = client.(yobj)
		if !ok {
			return fmt.Errorf("unexpected type of client at index %d: %T", i, client)
		}

		ids := yarr{}
		for _, id := range []string{"ip", "mac"} {
			val, _, valErr := fieldVal[string](c, id)
			if valErr != nil {
				return fmt.Errorf("client at index %d: %w", i, valErr)
			} else if val != "" {
				ids = append(ids, val)
			}
		}

		c["ids"] = ids
	}

	return nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check the ip and mac fields of each client in the config; make each a single plain string
2. Re-run migration after correcting types
3. If unsure which client is at fault, note the index reported in the message counts from the top of the clients list

Example fix

# before
clients:
  - name: x
    ip: [192.168.1.5]
# after
clients:
  - name: x
    ip: 192.168.1.5

// ensure ip/mac are strings before migrating
for k, v := range client {
    if (k == "ip" || k == "mac") && v != nil {
        if _, ok := v.(string); !ok { return fmt.Errorf("%s must be string", k) }
    }
}

func isStringField(v any) bool { _, ok := v.(string); return ok }

When it happens

Trigger: Migrating a config where a client's ip/mac field is quoted incorrectly or stored as a non-string YAML type (e.g. an IP written as a mapping or a list of IPs where a string is expected).

Common situations: Hand-crafted client entries with unusual YAML typing; configs migrated from other tools that emit structured values for ip/mac.

Related errors

• parsing config file for upgrade: %w
• generating new config: %w
• unknown current schema version %d
• unknown target schema version %d
• target schema version %d lower than current %d

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