hashicorp/nomad · error

Filter rule must begin with either '+' or '-': %q

Error message

Filter rule must begin with either '+' or '-': %q

What it means

Telemetry.PrefixFilters parses prefix_filter rules; a rule whose first character is neither '+' (allow) nor '-' (block) is invalid, so the telemetry metric filter cannot be built and agent startup/configuration fails.

Source

Thrown at command/agent/config.go:1509

	nt.PrefixFilter = slices.Clone(t.PrefixFilter)
	nt.FilterDefault = pointer.Copy(t.FilterDefault)
	nt.ExtraKeysHCL = slices.Clone(t.ExtraKeysHCL)
	return &nt
}

// PrefixFilters parses the PrefixFilter field and returns a list of allowed and blocked filters
func (t *Telemetry) PrefixFilters() (allowed, blocked []string, err error) {
	for _, rule := range t.PrefixFilter {
		if rule == "" {
			continue
		}
		switch rule[0] {
		case '+':
			allowed = append(allowed, rule[1:])
		case '-':
			blocked = append(blocked, rule[1:])
		default:
			return nil, nil, fmt.Errorf("Filter rule must begin with either '+' or '-': %q", rule)
		}
	}
	return allowed, blocked, nil
}

// Validate the telemetry configuration options. These are used by the agent,
// regardless of mode, so can live here rather than a structs package. It is
// safe to call, without checking whether the config object is nil first.
func (t *Telemetry) Validate() error {
	if t == nil {
		return nil
	}

	// Ensure we have durations that are greater than zero.
	if t.inMemoryCollectionInterval <= 0 {
		return errors.New("telemetry in-memory collection interval must be greater than zero")
	}
	if t.inMemoryRetentionPeriod <= 0 {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Prefix each rule with '+' to allow or '-' to block, e.g. "+web", "-db".
2. Check for config parsing that strips the leading character (quoting/escaping issues in HCL).
3. Trim whitespace only, never the sign, when building rule lists programmatically.

Example fix

// before
filters = ["web", "-db"]
// after
filters = ["+web", "-db"]

for _, r := range rules {
  if len(r) == 0 || (r[0] != '+' && r[0] != '-') {
    return fmt.Errorf("rule %q must start with + or -", r)
  }
}

When it happens

Trigger: Passing a filter rule string like "consul-service" (no + or - prefix) to the filter parsing in agent config.

Common situations: Copy-pasting filter expressions from docs without the prefix; splitting a comma-separated list that strips the leading + or -; users assuming bare names mean 'allow'.

Related errors

• wait config is nil or empty
• retry config is nil or empty
• fingerprint name cannot be empty
• rcp.accept_backlog interval must be greater than zero
• rcp.keep_alive_interval must be greater than zero

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/5e814363b721ff46. Report an issue: GitHub.