projectdiscovery/nuclei · error

Invalid userAgent: %s

Error message

Invalid userAgent: %s

What it means

Raised by toUserAgent when a UserAgentHolder is unmarshalled from YAML/JSON and the normalized value (TrimSpace + ToLower) is not in userAgentMappings. The only accepted values are 'random', 'off', 'default' and 'custom' (user_agent.go:26-31). It fires during config/template load, so it fails fast before any request is sent.

Source

Thrown at pkg/model/types/userAgent/user_agent.go:48

	Custom:  "custom",
}

func GetSupportedUserAgentOptions() []UserAgent {
	var result []UserAgent
	for index := UserAgent(1); index < limit; index++ {
		result = append(result, index)
	}
	return result
}

func toUserAgent(valueToMap string) (UserAgent, error) {
	normalizedValue := normalizeValue(valueToMap)
	for key, currentValue := range userAgentMappings {
		if normalizedValue == currentValue {
			return key, nil
		}
	}
	return -1, errors.New("Invalid userAgent: " + valueToMap)
}

func normalizeValue(value string) string {
	return strings.TrimSpace(strings.ToLower(value))
}

func (userAgent UserAgent) String() string {
	return userAgentMappings[userAgent]
}

// UserAgentHolder holds a UserAgent type. Required for un/marshalling purposes
type UserAgentHolder struct {
	Value UserAgent `mapping:"true"`
}

func (userAgentHolder UserAgentHolder) JSONSchema() *jsonschema.Schema {
	gotType := &jsonschema.Schema{
		Type:        "string",

View on GitHub (pinned to 265b3a3dec)

Solutions

1. Use one of the four allowed values: random, off, default, custom
2. Put the actual browser string in the dedicated custom UA field, not in the mode enum
3. Validate the config file with nuclei -validate before a run

Example fix

# before
user-agent: Mozilla/5.0 (compat)
# after
user-agent: custom
# and set the custom string in the dedicated field it drives

var validUserAgents = map[string]bool{"random": true, "off": true, "default": true, "custom": true}
func userAgentOK(s string) bool { return validUserAgents[strings.ToLower(strings.TrimSpace(s))] }

When it happens

Trigger: Setting a user-agent mode field to 'browser', 'mozilla', 'none' or an arbitrary UA string where the enum (random|off|default|custom) is expected.

Common situations: Confusing the mode enum with the actual UA string (the string belongs in a different field once mode is 'custom'); porting configs from other scanners with different option names.

Related errors

• validation failed for these fields
• Invalid severity: %s
• Invalid extractor type: %s
• Invalid matcher type: %s
• Invalid DNS request type: %s

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