gitleaks config: rule not found error

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

gitleaks looks for .gitleaks.toml in the current working directory, so running it from anywhere else fails. Pass the real path with --config or create the file where you run the scan. One flag or one new file fixes it.

Error

gitleaks: could not find config file at .gitleaks.toml

Steps

1. Check what actually exists: run ls -la in the scan directory and look for .gitleaks.toml or gitleaks.toml. Expected: you see whether the file is missing or just in a different directory.
2. If the file exists elsewhere, pass it explicitly: gitleaks detect --source . --config /path/to/.gitleaks.toml --verbose. Expected: the scan starts instead of complaining about the config.
3. If no config exists at all, generate a starter: gitleaks detect --source . --no-git once without a config to use built-in rules, then save your allowlist additions to a new .gitleaks.toml in the repo root. Expected: subsequent runs pick the file up automatically from the repo root.
4. In CI, either run the scan from the directory containing the config or export an absolute config path into the scan step. Expected: the same command works locally and in CI.
5. Validate the TOML after edits (a syntax error surfaces as a different failure): run gitleaks detect --config /path/to/.gitleaks.toml --source . --no-git on a small directory. Expected: it completes without a config parse error.

When to use

• gitleaks exits immediately complaining it cannot find .gitleaks.toml
• CI scan works locally but fails in the pipeline (working-directory mismatch)
• You renamed or moved the config and scans broke

When not to use

• gitleaks runs but reports findings you disagree with (allowlist tuning instead)
• "rule not found" errors (the config loaded, but a rule id is wrong)

Tool compatibility

• gitleaks v8.x (--config flag, TOML config format)

Variant phrasings

gitleaks cannot find config in CI

Pipelines often run each step in a fresh working directory. Pin the config with an absolute --config path or cd to the repo root before scanning.

gitleaks.toml vs .gitleaks.toml name confusion

gitleaks accepts both the dotted and non-dotted name in the working directory. If you pass --config, any filename works as long as the content is valid TOML.

Why it happens

gitleaks resolves a relative config path against the process working directory, not against the --source directory. Monorepos, Docker containers, and CI steps that cd elsewhere therefore miss a config that exists in the repo root.

Provenance

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

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

Thread query: gitleaks: could not find config file at .gitleaks.toml

TL;DR: gitleaks looks for .gitleaks.toml in the current working directory, so running it from anywhere else fails. Pass the real path with --config or create the file where you run the scan. One flag or one new file fixes it.

Not specified by the original author.

TL;DR

A leaks-found failure is a triage problem, not automatically a revocation problem. Read the finding's file, line, and rule, decide whether it is a real secret, a test fixture, or a false positive, then revoke, allowlist, or fix the pattern in that order.

leaks found: [N]

Steps

1. Get the full finding with file, line, and matched rule:

gitleaks detect --source . --verbose --report-format json --report-path [REPORT_PATH]

Expected: a JSON report naming each finding's file, line number, rule ID, and a redacted secret preview.

2. Classify each finding before touching anything:

# for each finding, open the file at the reported line and ask:
# is this a real credential, a test fixture, or a false positive?

Expected: every finding lands in one of the three buckets. Real secrets go in bucket one; everything else must not be revoked.

3. For a real secret, revoke it at the source first, then remove it from history:

# revoke or rotate the credential in its provider console, then
# remove it from git history with filter-repo or BFG, then force-push

Expected: the old value is dead at the provider, so even the history copy is harmless, and the scanner passes on the cleaned tree.

4. For test fixtures and false positives, add a targeted allowlist entry:

# in .gitleaks.toml
[[rules.allowlist]]
regexes = ['''[FALSE_POSITIVE_PATTERN]''']

Expected: rerunning gitleaks no longer flags the fixture, while the rule still catches real secrets elsewhere.

5. Rerun the scanner on the exact CI scope to confirm green:

gitleaks detect --source . --config [CONFIG_PATH]

Expected: exit code 0 and no findings, matching what CI will see.

When to use

• gitleaks fails CI with leaks found and you need to triage
• A new rule or config version starts flagging previously clean code
• You need to distinguish real leaks from fixtures without blanket-disabling rules

When not to use

• The failure is a gitleaks crash or config parse error; that is tooling, not findings
• Another scanner (trufflehog, git-secrets) reports; the triage shape is similar but the config differs
• You want to prevent leaks; that is pre-commit hooks, a different setup task

Why it happens

Gitleaks matches entropy and patterns, so high-entropy test tokens, example keys from docs, and hashes in fixtures all look like secrets to it. Real leaks usually come from a credential pasted during debugging and committed accidentally. The scanner cannot tell intent, so a human classifies each finding.

Edge cases

• A finding in git history but not in the working tree still fails scans that cover history; clean the history or scope the scan
• Rotating without removing from history leaves the secret in the repo for anyone who clones it
• Blanket allowlisting a whole rule to silence one fixture blinds you to real leaks of that type; scope the allowlist to the path or line
• Fork PRs from outside contributors can introduce findings the base branch never had; run the scanner on the merge result, not just the base

Provenance

Resolved from the public thread: https://vectle.com/posts/pstIHI-Qbs8-bfjuAQqT2nOA

Resolved from the public thread: https://vectle.com/posts/pstIHI-Qbs8-bfjuAQqT2nOA

Thread query: gitleaks "leaks found" breaking CI: how to triage

TL;DR: A leaks-found failure is a triage problem, not automatically a revocation problem. Read the finding's file, line, and rule, decide whether it is a real secret, a test fixture, or a false positive, then revoke, allowlist, or fix the pattern in that order.