What causes "unknown matcher type specified: %s" in projectdiscovery/nuclei?

Use exactly one of: status, size, word, regex, binary, dsl, xpath (singular 'word')

unknown matcher type specified: %s

Error message

unknown matcher type specified: %s

What it means

Template compilation error from Matcher.CompileMatchers (pkg/operators/matchers/compile.go:30). The matcher's `type:` is mapped via toMatcherTypes, which normalizes (trim+lowercase) and compares against {status, size, word, regex, binary, dsl, xpath}. Any other value — including a missing `type:` (zero-value String() is "") — fails here. Note the singular form: `word`, not `words`.

Source

Thrown at pkg/operators/matchers/compile.go:30

)

// CompileMatchers performs the initial setup operation on a matcher
func (matcher *Matcher) CompileMatchers() error {
	var ok bool

	// Support hexadecimal encoding for matchers too.
	if matcher.Encoding == "hex" {
		for i, word := range matcher.Words {
			if decoded, err := hex.DecodeString(word); err == nil && len(decoded) > 0 {
				matcher.Words[i] = string(decoded)
			}
		}
	}

	// Set up the matcher type
	computedType, err := toMatcherTypes(matcher.GetType().String())
	if err != nil {
		return fmt.Errorf("unknown matcher type specified: %s", matcher.Type)
	}

	matcher.matcherType = computedType

	// Validate the matcher structure
	if err := matcher.Validate(); err != nil {
		return err
	}

	// By default, match on body if user hasn't provided any specific items
	if matcher.Part == "" && matcher.GetType() != DSLMatcher {
		matcher.Part = "body"
	}

	// Compile the regexes (with shared cache)
	for _, regex := range matcher.Regex {
		if cached, err := cache.Regex().GetIFPresent(regex); err == nil && cached != nil {
			matcher.regexCompiled = append(matcher.regexCompiled, cached)

View on GitHub (pinned to 265b3a3dec)

Solutions

Use exactly one of: status, size, word, regex, binary, dsl, xpath (singular 'word')
Fix indentation so `type:` is a sibling of the matcher's other keys
Validate with `nuclei -validate -t template.yaml` or `make template-validate`
When embedding via SDK, print matcher.Type — the error includes the raw string

Example fix

# before
matchers:
  - type: words
    words:
      - 'admin'
# after
matchers:
  - type: word
    words:
      - 'admin'

Defensive patterns

Strategy: validation

Validate before calling

var validMatcherTypes = map[string]bool{"status": true, "size": true, "word": true, "regex": true, "binary": true, "dsl": true, "xpath": true}

func matcherTypeOK(t string) bool { return validMatcherTypes[strings.ToLower(strings.TrimSpace(t))] }

Type guard

type MatcherSpec struct{ Type string; Words []string; Regex []string; Status []int }

func (m MatcherSpec) Valid() bool { return matcherTypeOK(m.Type) }

Try / catch

if err := m.CompileMatchers(); err != nil {
	if strings.HasPrefix(err.Error(), "unknown matcher type") {
		// author error: echo template path + allowed type list
	}
	return err
}

Prevention

It's 'word', not 'words'; status/size are singular concepts too
Run nuclei -validate in template CI
Generate matchers from typed structs; avoid hand-typed maps

When it happens

Trigger: `type: words` (plural), `type: Status` alone is fine (normalized) but `type: status-code`, `type: header`, or a missing/misspelled type fails; also matcher blocks whose YAML indentation detaches `type:` from the matcher map.

Common situations: Writing `words:` field with `type: words` by symmetry; templates ported from other scanners with different type vocabularies; YAML list/indent mistakes that drop the type key during unmarshal.

Related errors

AI-assisted analysis of projectdiscovery/nuclei@265b3a3dec (2026-08-15). Data as JSON: /api/errors/88e2d85f053fae8a. Report an issue: GitHub.