kgretzky/evilginx2 · error

credentials: missing username `key` field

Error message

credentials: missing username `key` field

What it means

Thrown while validating the credentials section of a phishlet: fp.Credentials.Username.Key is nil. Every phishlet must declare how to identify the username input ('key' is the regex matching the input field name/id), and it is missing. The phishlet fails to load.

Source

Thrown at core/phishlet.go:592

				return fmt.Errorf("auth_tokens: 'header' not found for http auth token")
			}

			err := p.addHttpAuthToken(p.paramVal(*at.Domain), p.paramVal(*at.Path), p.paramVal(*at.Name), p.paramVal(*at.Header))
			if err != nil {
				return err
			}
		}
	}
	for _, au := range fp.AuthUrls {
		re, err := regexp.Compile(p.paramVal(au))
		if err != nil {
			return err
		}
		p.authUrls = append(p.authUrls, re)
	}

	if fp.Credentials.Username.Key == nil {
		return fmt.Errorf("credentials: missing username `key` field")
	}
	if fp.Credentials.Username.Search == nil {
		return fmt.Errorf("credentials: missing username `search` field")
	}
	if fp.Credentials.Password.Key == nil {
		return fmt.Errorf("credentials: missing password `key` field")
	}
	if fp.Credentials.Password.Search == nil {
		return fmt.Errorf("credentials: missing password `search` field")
	}

	p.username.key, err = regexp.Compile(p.paramVal(*fp.Credentials.Username.Key))
	if err != nil {
		return fmt.Errorf("credentials: %v", err)
	}

	p.username.search, err = regexp.Compile(p.paramVal(*fp.Credentials.Username.Search))
	if err != nil {

View on GitHub (pinned to 4c0988a1d9)

Solutions

1. Add 'username: { key: <regex>, search: <regex> }' under credentials in the phishlet YAML
2. Ensure 'key' is indented under credentials.username, not a sibling of it
3. Copy the credentials block from a known-good example phishlet

Example fix

// before
credentials:
  username:
    search: 'user=([^&]*)'
// after
credentials:
  username:
    key: 'username'
    search: 'user=([^&]*)'

if cfg.Credentials.Username.Key == nil || *cfg.Credentials.Username.Key == "" {
  return errors.New("credentials: missing username key")
}

func hasUsernameKey(fp FakePost) bool { return fp.Credentials.Username.Key != nil && *fp.Credentials.Username.Key != "" }

When it happens

Trigger: Loading a phishlet whose credentials.username block lacks 'key', or whose YAML structure puts username fields at the wrong nesting level under credentials.

Common situations: Minimal/hand-written phishlet missing the username block; indentation error detaching 'key' from 'username'; migrating an old phishlet format missing this field.

Related errors

• credentials: missing username `search` field
• credentials: missing password `key` field
• credentials: missing password `search` field
• auth_tokens: 'search' not found for body auth token
• auth_tokens: 'domain' not found for http auth token

AI-assisted analysis of kgretzky/evilginx2@4c0988a1d9 (2026-09-05). Data as JSON: /api/errors/064715836eb9c48f. Report an issue: GitHub.