# fail2ban troubleshooting

> fail2ban troubleshooting: match your symptom or exact error message to the fix, and use a 6-step debugging routine that finds most fail2ban problems in minutes.
>
> Source: https://fail2ban.dev/troubleshooting/ · Updated 2026-10-25 · Checked against fail2ban 1.1.1
> fail2ban.dev is an independent guide, not the official fail2ban project.

Most fail2ban problems come down to one of three things: the jail can't see the right log lines, the filter doesn't match them, or the ban never reaches the firewall that actually handles the traffic. Start with `sudo fail2ban-client status <jail>`. If `Total failed` stays at 0, the problem is the log or the filter. If IPs are banned but can still connect, the problem is the firewall.

## Find your problem by symptom

| Symptom or exact message | Go to |
|---|---|
| Failed logins pile up but nobody gets banned | [fail2ban not banning](/troubleshooting/not-banning/) |
| `Total failed` stays at 0 | [fail2ban not banning](/troubleshooting/not-banning/) |
| IP shows in `Banned IP list` but can still connect | [Banned but not blocked](/troubleshooting/not-banning/#part-2-the-ip-is-banned-but-still-connects) |
| No `f2b-` chain or table in iptables or nftables | [Banned but not blocked](/troubleshooting/not-banning/#part-2-the-ip-is-banned-but-still-connects) |
| `Have not found any log file for sshd jail` | [No log file found](/troubleshooting/no-log-file/) |
| `No file(s) found for glob` / `No file is currently monitored` | [No log file found](/troubleshooting/no-log-file/) |
| `Failed to access socket path: /var/run/fail2ban/fail2ban.sock. Is fail2ban running?` | [Could not find server](/troubleshooting/could-not-find-server/) |
| `Could not find server` | [Could not find server](/troubleshooting/could-not-find-server/) |
| `status=255/EXCEPTION`, service failed, won't start | [Exit code 255](/troubleshooting/exit-code-255/) |
| `No module named 'asynchat'` (Python 3.12) | [Exit code 255](/troubleshooting/exit-code-255/) |
| Bans `127.0.0.1`, a proxy, a load balancer or Cloudflare | [Bans the proxy IP](/troubleshooting/reverse-proxy-ip/) |
| Banned, but the Docker container is still reachable | [Docker: banned but not blocked](/guides/docker/) |
| `'allowipv6' not defined in 'Definition'. Using default one: 'auto'` | [allowipv6 warning](/troubleshooting/config-errors/#allowipv6-not-defined-in-definition-using-default-one-auto) |
| `No failure-id group in …`, `No section: 'Definition'`, `nft: not found` | [Config and regex errors](/troubleshooting/config-errors/) |
| `Sorry but the jail 'x' does not exist` | [Config and regex errors](/troubleshooting/config-errors/) |
| Ban emails never arrive | [Email not sending](/config/email-alerts/#email-alerts-not-sending-troubleshooting) |
| fail2ban uses 100% CPU, lots of memory, or `too many open files` | [High CPU or memory](/troubleshooting/high-cpu/) |

## The 6-step debugging routine

Work through these in order. Each step either finds the fault or rules out a whole category of causes.


1. **Check the jail is running and counting.** `sudo fail2ban-client status` lists the active jails. `sudo fail2ban-client status sshd` shows `Currently failed`, `Total failed` and either `File list` or `Journal matches`. A jail missing from the list was never enabled or failed to load.
2. **Dump the effective configuration.** `sudo fail2ban-client -d` prints the exact settings the client would send to the server after reading `jail.conf`, `jail.d/` and `jail.local`. Grep it for your jail to confirm `logpath`, `backend`, `maxretry`, `findtime`, `ignoreip` and the actions.
3. **Test the filter against the real log.** `sudo fail2ban-regex /var/log/auth.log sshd` (or `sudo fail2ban-regex systemd-journal sshd` for journal jails) shows how many lines match. Zero matches means the filter or the log source is wrong.
4. **Watch the log at DEBUG level.** `sudo fail2ban-client set loglevel DEBUG`, then `sudo tail -f /var/log/fail2ban.log` while you reproduce the failure. Set it back with `sudo fail2ban-client set loglevel INFO`.
5. **Check the firewall.** After a ban, `sudo nft list ruleset | grep -A5 f2b` or `sudo iptables -S | grep f2b` must show the address or set. fail2ban creates its table or chain at the first ban, not at startup.
6. **Check the ignore list.** `sudo fail2ban-client get sshd ignoreip` and `sudo fail2ban-client get sshd ignoreself`. Testing from the server itself or from a whitelisted network never produces a ban.

The commands for steps 1 and 2 look like this:

```bash
sudo fail2ban-client status sshd
sudo fail2ban-client -d | grep "'sshd'"
```

```text
$ sudo fail2ban-client status sshd
Status for the jail: sshd
|- Filter
|  |- Currently failed:	2
|  |- Total failed:	6
|  `- File list:	/var/log/auth.log
`- Actions
   |- Currently banned:	1
   |- Total banned:	1
   `- Banned IP list:	203.0.113.42
```

> **Make one change at a time**
After every config edit, run `sudo fail2ban-client -t` (it prints `OK: configuration test is successful` or tells you what's wrong), then `sudo fail2ban-client reload`. Changing five things at once makes it impossible to tell which one fixed or broke the jail.

## All troubleshooting guides


- [fail2ban not banning](/troubleshooting/not-banning/) — Failures logged but no bans: logpath, backend, filter, timestamps, ignoreip, thresholds.
- [Banned but still connecting](/troubleshooting/not-banning/#part-2-the-ip-is-banned-but-still-connects) — Wrong port, wrong firewall, open connections, IPv6, rule order.
- [No log file found for jail](/troubleshooting/no-log-file/) — "Have not found any log file for sshd jail" on Debian 12 and elsewhere.
- [Failed to access socket / server](/troubleshooting/could-not-find-server/) — "Is fail2ban running?" and "Could not find server".
- [Exit code 255 / service failed](/troubleshooting/exit-code-255/) — Find the real error behind status=255/EXCEPTION.
- [Bans the proxy or Cloudflare IP](/troubleshooting/reverse-proxy-ip/) — Log the real client IP and ban it at the right layer.
- [Docker: banned but not blocked](/guides/docker/) — DOCKER-USER chain, nftables forward hook, fail2ban in a container.
- [allowipv6 not defined warning](/troubleshooting/config-errors/#allowipv6-not-defined-in-definition-using-default-one-auto) — What the warning means and how to silence it.
- [Config and regex errors](/troubleshooting/config-errors/) — Every common startup and reload error, quoted exactly.
- [Email alerts not sending](/config/email-alerts/#email-alerts-not-sending-troubleshooting) — MTA, action, destemail and sender fixes.
- [High CPU or memory](/troubleshooting/high-cpu/) — Polling backends, huge logs, slow regexes, journal file descriptors.

## FAQ

### How do I debug fail2ban?

Raise the log level with `sudo fail2ban-client set loglevel DEBUG`, follow `/var/log/fail2ban.log` while you reproduce the problem, and test the filter with `fail2ban-regex` against the real log. `sudo fail2ban-client -d` shows the effective configuration after all files are merged.

### How do I check that my fail2ban configuration is valid?

Run `sudo fail2ban-client -t`. It reads every config file, builds the jails and prints `OK: configuration test is successful`, or `ERROR: test configuration failed` with the reason above it. Run it before every reload or restart so a typo doesn't take the service down.