projectdiscovery/nuclei · error

please set custom_user_agent in the template

Error message

please set custom_user_agent in the template

What it means

Headless requests support a user_agent mode enum (off, default, random, custom). Mode `custom` requires the sibling custom_user_agent field to hold the UA string; if it is empty, Compile fails with this error. Other modes are self-sufficient: off sets a blank UA, default leaves nuclei' default, random picks from uagent.

Source

Thrown at pkg/protocols/headless/headless.go:135

	}

	if len(request.Payloads) > 0 {
		var err error
		request.generator, err = generators.New(request.Payloads, request.AttackType.Value, options.TemplatePath, options.Catalog, options.Options.AttackType, request.options.Options)
		if err != nil {
			return errors.Wrap(err, "could not parse payloads")
		}
	}

	// Compile User-Agent
	switch request.UserAgent.Value {
	case useragent.Off:
		request.compiledUserAgent = " "
	case useragent.Default:
		request.compiledUserAgent = ""
	case useragent.Custom:
		if request.CustomUserAgent == "" {
			return errors.New("please set custom_user_agent in the template")
		}
		request.compiledUserAgent = request.CustomUserAgent
	case useragent.Random:
		userAgent := uagent.PickRandom()
		request.compiledUserAgent = userAgent.Raw
	}

	if len(request.Matchers) > 0 || len(request.Extractors) > 0 {
		compiled := &request.Operators
		compiled.ExcludeMatchers = options.ExcludeMatchers
		compiled.TemplateID = options.TemplateID
		if err := compiled.Compile(); err != nil {
			return errors.Wrap(err, "could not compile operators")
		}
		request.CompiledOperators = compiled
	}

	if len(request.Fuzzing) > 0 {

View on GitHub (pinned to 265b3a3dec)

Solutions

1. Add custom_user_agent: "Mozilla/5.0 ..." next to user_agent: custom
2. Or switch to an already-sufficient mode: user_agent: default, random, or off
3. Validate the template before running

Example fix

# before
user_agent: custom

# after
user_agent: custom
custom_user_agent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36"

if request.UserAgent.Value == useragent.Custom && strings.TrimSpace(request.CustomUserAgent) == "" {
    return errors.New("user_agent: custom requires custom_user_agent to be set")
}

When it happens

Trigger: A headless request block containing `user_agent: custom` without a custom_user_agent value (or with an empty one).

Common situations: Editing a template from `user_agent: random` to custom and forgetting the string; indentation moving custom_user_agent outside the request block.

Related errors

• payload concurrency must be at least 1
• Invalid userAgent: %s
• Invalid action type: %s
• attribute can't be empty
• event not recognized

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