What causes "invalid tag: %q" in AdguardTeam/AdGuardHome?

Create the missing tag via the tag settings API/UI first, then retry Add/Update

invalid tag: %q

Error message

invalid tag: %q

What it means

Validation error from persistent client validation: one of the client's tags is not present in the global sorted list of known tags (allTags). Tags must exist in the server's tag set before they can be attached to a client.

Source

Thrown at internal/client/persistent.go:161

		return errors.Error("uid required")
	}

	conf, err := proxy.ParseUpstreamsConfig(c.Upstreams, &upstream.Options{
		Logger: l.With(aghslog.KeyUpstreamType, aghslog.UpstreamTypeTest),
	})
	if err != nil {
		return fmt.Errorf("invalid upstream servers: %w", err)
	}

	err = conf.Close()
	if err != nil {
		l.ErrorContext(ctx, "client: closing upstream config", slogutil.KeyError, err)
	}

	for _, t := range c.Tags {
		_, ok := slices.BinarySearch(allTags, t)
		if !ok {
			return fmt.Errorf("invalid tag: %q", t)
		}
	}

	// TODO(s.chzhen):  Move to the constructor.
	slices.Sort(c.Tags)

	return nil
}

// SetIDs parses a list of strings into typed fields and returns an error if
// there is one.
func (c *Persistent) SetIDs(ids []string) (err error) {
	for _, id := range ids {
		err = c.setID(id)
		if err != nil {
			return err
		}
	}

View on GitHub (pinned to b41aefbe51)

Solutions

Create the missing tag via the tag settings API/UI first, then retry Add/Update
Check for typos and case differences between the client's tag and the configured tags
If a tag was renamed, update the client's Tags slice to the new name

Example fix

// before
c.Tags = []string{"device-tv"} // tag "device-tv" not defined

// after
// 1. create tag "device-tv" in settings, then:
c.Tags = []string{"device-tv"}

Defensive patterns

Strategy: validation

Validate before calling

known := map[string]bool{}
for _, t := range allTags { known[t] = true }
for _, t := range c.Tags {
    if !known[t] { /* reject or auto-create tag */ }
}

Try / catch

if err := s.Add(ctx, c); err != nil && strings.Contains(err.Error(), "invalid tag") { /* create tag, then retry */ }

Prevention

Create tags via the settings API before assigning them to clients
Use dropdowns of existing tags in UIs instead of free-text input

When it happens

Trigger: Calling Storage.Add or Storage.Update with c.Tags containing a tag name that was never created via the tag configuration API (checked by binary search against allTags).

Common situations: Hardcoding tag names in config or scripts instead of creating them first, renaming/deleting a tag while clients still reference it, case mismatches between configured tag names and client tags.

Related errors

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