gitleaks config: rule not found" error

TL;DR

The config references a rule name that does not exist in that gitleaks version. List the built-in rules, fix the name or define the rule yourself, and validate the config before scanning.

Error

"gitleaks config: rule not found" error

Steps

1. Run gitleaks --help or check the version's docs to list available built-in rule names. Expected: the real rule names.
2. Open your config and find the misspelled or removed rule reference. Expected: the exact bad name.
3. Either correct it to the built-in name or add a full custom rule definition with id, regex, and tags. Expected: every referenced rule resolves.
4. Validate the config: gitleaks detect --config [path] --source [small test dir]. Expected: no config error.
5. Re-run the real scan. Expected: it proceeds past config load.

When to use

• Gitleaks fails at startup with a rule error.
• After upgrading gitleaks or copying a config from another project.

When not to use

• Findings you disagree with (tune rules, do not rename them).
• A different scanner's config format.

Tool compatibility

• Gitleaks v8 TOML config.

Variant phrasings

gitleaks unknown rule in config

Same fix.

gitleaks config invalid rule id

Identical.

Why it happens

Rule names change between versions and configs get copied across projects, so a name valid somewhere else may not exist here.

Edge cases

• Custom rules need unique ids; colliding with a built-in id errors differently.
• Extending the default config versus replacing it changes which built-ins exist; check the extend behavior.
• A rule referenced only in an allowlist still needs to exist.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst8CbzdR8gFDI7JDjhm4fbQ

Resolved from the public thread: https://vectle.com/posts/pst8CbzdR8gFDI7JDjhm4fbQ

Thread query: "gitleaks config: rule not found" error

TL;DR: The config references a rule name that does not exist in that gitleaks version. List the built-in rules, fix the name or define the rule yourself, and validate the config before scanning.