must contain at least one check for: commits, paths, regexes

Error message

must contain at least one check for: commits, paths, regexes, or stopwords

What it means

Every allowlist in a gitleaks config must contain at least one matching criterion: commits, paths, regexes, or stopwords. Allowlist.Validate() rejects fully-empty allowlists because an allowlist with no criteria would either match nothing (useless) or, if the condition logic were inverted, suppress everything. This fires while parsing [[allowlists]] or [[rules.allowlists]] blocks during config load.

Source

Thrown at config/allowlist.go:80

	// commitMap is a normalized version of Commits, used for efficiency purposes.
	// TODO: possible optimizations so that both short and long hashes work.
	commitMap    map[string]struct{}
	regexPat     *regexp.Regexp
	pathPat      *regexp.Regexp
	stopwordTrie *ahocorasick.Trie
}

func (a *Allowlist) Validate() error {
	if a.validated {
		return nil
	}

	// Disallow empty allowlists.
	if len(a.Commits) == 0 &&
		len(a.Paths) == 0 &&
		len(a.Regexes) == 0 &&
		len(a.StopWords) == 0 {
		return errors.New("must contain at least one check for: commits, paths, regexes, or stopwords")
	}

	// Deduplicate commits and stopwords.
	if len(a.Commits) > 0 {
		uniqueCommits := make(map[string]struct{})
		for _, commit := range a.Commits {
			// Commits are case-insensitive.
			uniqueCommits[strings.TrimSpace(strings.ToLower(commit))] = struct{}{}
		}
		a.Commits = maps.Keys(uniqueCommits)
		a.commitMap = uniqueCommits
	}
	if len(a.StopWords) > 0 {
		uniqueStopwords := make(map[string]struct{})
		for _, stopWord := range a.StopWords {
			uniqueStopwords[strings.ToLower(stopWord)] = struct{}{}
		}

View on GitHub (pinned to b58d3f102c)

Solutions

Add at least one criterion to the allowlist, e.g. a path regex: paths = [['''\.md$''']].
If the allowlist is not needed, delete the whole [[allowlists]] or [[rules.allowlists]] block instead of leaving it empty.
Check key spelling and table nesting: keys must be commits, paths, regexes, stopwords directly under the allowlist table.
Run gitleaks with --verbose or use `gitleaks detect --config-path=... --no-git` on a tiny repo to smoke-test the config after edits.

Example fix

# before (TOML)
[[allowlists]]
description = "ignore docs"

# after (TOML)
[[allowlists]]
description = "ignore docs"
paths = ['''\.md$''']

Defensive patterns

Strategy: validation

Validate before calling

# python: catch empty allowlist tables before running gitleaks
import tomllib

cfg = tomllib.load(open("gitleaks.toml", "rb"))
for name, als in [("allowlists", cfg.get("allowlists", []))] + [
    (f"rules[{i}].allowlists", r.get("allowlists", [])) for i, r in enumerate(cfg.get("rules", []))
]:
    for j, a in enumerate(als):
        if not any(a.get(k) for k in ("commits", "paths", "regexes", "stopwords")):
            raise SystemExit(f"empty allowlist: {name}[{j}] has no commits/paths/regexes/stopwords")

Prevention

Never commit placeholder allowlist blocks; add criteria or delete the block.
Validate the TOML in CI (e.g. with the snippet above) before any scan step.
Double-check key spelling: commits, paths, regexes, stopwords.

When it happens

Trigger: Declaring [[allowlists]] with only a description (or only matchCondition) and no commits/paths/regexes/stopwords; the same for a [[rules.allowlists]] table under a rule. parseAllowlist -> Validate() sees all four slices empty and returns this error, wrapped as '[[allowlists]] must contain at least one check...'.

Common situations: Starting an allowlist block as a placeholder intending to fill it later; YAML/TOML indentation mistakes that detach the keys from the allowlist table so they parse as empty; deleting the last criterion during cleanup; upgrading configs where a typo'd key name (e.g. stopwords vs stopWords) silently yields an empty slice.

Related errors

AI-assisted analysis of gitleaks/gitleaks@b58d3f102c (2026-08-15). Data as JSON: /api/errors/dd9969e983a74e16. Report an issue: GitHub.