AdguardTeam/AdGuardHome · error

unexpected type of client at index %d: %T

Error message

unexpected type of client at index %d: %T

What it means

During config schema migration to v6, each entry in the clients list failed to assert to the expected map type (map[string]any from YAML/JSON decoding). The schema expects every client to be a mapping object, but at least one is a scalar, list, or of another Go type.

Source

Thrown at internal/configmigrate/v6.go:42

//	   'mac': 'AA:AA:AA:AA:AA:AA'
//	   'ids':
//	   - '127.0.0.1'
//	   - 'AA:AA:AA:AA:AA:AA'
//	  # …
//	# …
func (m *Migrator) migrateTo6(_ context.Context, diskConf yobj) (err error) {
	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. Inspect the clients: section of your YAML config; ensure every item is an indented mapping (e.g. '- name: x\n ids: [...]'), not a bare string
2. Fix or remove malformed client entries and re-run the migration
3. Restore config.yaml from backup if the file is corrupted

Example fix

# before
clients:
  - 'laptop'
# after
clients:
  - name: laptop
    ids: [192.168.1.10]

// before migrating, check each client is a mapping
for i, c := range rawClients {
    if _, ok := c.(map[string]any); !ok {
        return fmt.Errorf("client %d is not a mapping", i)
    }
}

func isClientMap(v any) bool { _, ok := v.(map[string]any); return ok }

When it happens

Trigger: Migrating an old AdGuard Home YAML config where a client entry under 'clients:' is written as a plain string or list instead of a nested mapping of fields.

Common situations: Hand-edited YAML config files, configs produced by very old AdGuard Home versions or third-party tools, or a YAML indentation mistake that turns a client block into a scalar.

Related errors

• parsing config file for upgrade: %w
• generating new config: %w
• unexpected type of upstream field: %T
• persistent client at index %d: unexpected type %T
• filters: at index %d: expected object, got %T

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