fail2ban exit code 255: service failed to start

fail2ban.service: Main process exited, code=exited, status=255/EXCEPTION means fail2ban-server stopped because it couldn't build its configuration or start a jail. To see the actual cause, run sudo fail2ban-client -t. It tests every config file and prints the failing jail and reason. The most common causes are a missing log file (Have not found any log file for sshd jail), a typo in jail.local, and fail2ban 1.0.x on Python 3.12.

sudo fail2ban-client -t
sudo journalctl -u fail2ban -b --no-pager | tail -40

Why 255, and why the service stays down#

fail2ban-server exits with code 255 whenever startup fails: configuration errors, a jail that can't be created, an exception during start. The upstream systemd unit contains RestartPreventExitStatus=0 255. systemd deliberately doesn't retry, because a broken config would fail the same way every time. So the service sits in failed until you fix the cause and start it again. Meanwhile fail2ban-client reports Failed to access socket path … Is fail2ban running?.

Step 1: get the real error message#

Try these in order. Stop as soon as one shows an ERROR line.

1. Test the configuration. This reads everything and stops on the first fatal error, without touching the running system:

sudo fail2ban-client -t

Success prints OK: configuration test is successful. Failure prints the error lines followed by ERROR: test configuration failed.

2. Read the journal for this boot. fail2ban's own log file may not have been opened yet when it failed, so startup errors often land only in the journal:

sudo journalctl -u fail2ban -b --no-pager | tail -40
sudo tail -n 50 /var/log/fail2ban.log

Look at the lines above Main process exited, code=exited, status=255/EXCEPTION. One of them starts with ERROR.

3. Run the server in the foreground. This is the same command the unit runs, but with logging sent to your terminal:

sudo systemctl stop fail2ban
sudo fail2ban-server -xf --logtarget=stderr start

-x removes a stale socket, -f keeps it in the foreground, and --logtarget=stderr overrides the log target from fail2ban.conf. Add -v (or -vv) for more detail, including Python tracebacks. If it starts cleanly, stop it with Ctrl+C and start the service normally.

4. Dump the parsed configuration. sudo fail2ban-client -d prints the command stream the client would send, after all .conf, .local and jail.d/ files are merged. It's useful to see which value really wins for logpath, backend or action.

Cause 1: a jail's log file doesn't exist#

ERROR   Failed during configuration: Have not found any log file for sshd jail

This is the most common cause on Debian 12, where there's no /var/log/auth.log because rsyslog isn't installed. Add backend = systemd to [sshd] in jail.local, or correct the logpath. Full fix on Have not found any log file for sshd jail.

Cause 2: fail2ban 1.0.x on Python 3.12 ("No module named 'asynchat'")#

ERROR   No module named 'asynchat'

Python 3.12 removed the asyncore and asynchat modules that fail2ban 1.0.2 and older import. fail2ban 1.1.0 (April 2024) added support for Python 3.12 and 3.13 by bundling those modules. Any older fail2ban on Python 3.12+ exits with 255 straight away.

• Ubuntu 24.04 LTS shipped this bug at release. The fixed package, 1.0.2-3ubuntu0.1, has been in noble-updates since mid-2024. Upgrade with sudo apt update && sudo apt install --only-upgrade fail2ban.
• pip or source installs on Python 3.12+: install fail2ban 1.1.0 or newer (current: 1.1.1).
• Workarounds that install pyasynchat/pyasyncore with pip --break-system-packages work, but they modify the system Python. Upgrading fail2ban is cleaner.

Check what you have:

fail2ban-client --version
python3 --version
apt policy fail2ban      # Debian/Ubuntu

Cause 3: a syntax or interpolation error in jail.local#

fail2ban's config files are INI files parsed by Python's configparser, which is strict. These messages stop startup:

• File contains no section headers. means an option appears before the first [section] line, often from a pasted snippet that's missing [DEFAULT] or [sshd].
• While reading from '/etc/fail2ban/jail.local' [line 12]: option 'bantime' in section 'sshd' already exists means the same option appears twice in one section.
• While reading from … : section 'sshd' already exists means the same [section] appears twice in one file.
• '%' must be followed by '%' or '(', found: … means a literal % in a value. Write it as %%.
• Bad value substitution: option 'action' in section 'sshd' contains an interpolation key 'destemail' which is not a valid option name. means a %(name)s reference to something that isn't defined.

Each one, with the fix, is on config and regex errors.

Cause 4: unknown filter or action#

ERROR   Found no accessible config files for 'filter.d/myapp' under /etc/fail2ban
ERROR   Unable to read the filter 'myapp'
ERROR   Errors in jail 'myapp'. Skipping...

The jail names a filter (or action) that doesn't exist in filter.d/ (or action.d/). Remember that filter = %(__name__)s is the default, so a jail called [myapp] without a filter = line looks for filter.d/myapp.conf. Depending on the error, fail2ban skips just that jail or refuses to start. Fix the name or create the file. The filter library lists every bundled filter.

Cause 5: the backend can't load#

ERROR   NOK: ("Failed to initialize any backend for Jail 'sshd'",)

The jail asked for backend = systemd (or pyinotify) and the Python module is missing. Install python3-systemd (or python3-pyinotify), or use backend = auto for file-based jails. See backends.

Cause 6: an action or filter regex fails at jail start#

Errors from the server itself come back to the client as ERROR NOK: (…). Typical ones:

• No failure-id group in '…': a custom failregex without <HOST>.
• Unable to compile regular expression '…' followed by Python's reason, such as unterminated character set or missing ), unterminated subpattern. That's a syntax error in a custom regex.

Test custom filters with fail2ban-regex before you enable them. Both cases are covered on config and regex errors.

Confirm it's fixed#

sudo fail2ban-client -t
sudo systemctl reset-failed fail2ban
sudo systemctl start fail2ban
sudo systemctl status fail2ban --no-pager
sudo fail2ban-client status

The unit should be active (running) and fail2ban-client status should list your jails. If one jail is missing from the list, it was skipped; search /var/log/fail2ban.log for Errors in jail. More about reading the log on fail2ban logs.

FAQ#

What does status=255/EXCEPTION mean for fail2ban?#

fail2ban-server exited with code 255 because startup failed, usually because of a configuration error, a missing log file or an unloadable backend. systemd doesn't restart it on 255. Run sudo fail2ban-client -t or sudo journalctl -u fail2ban -b to see the error line printed just before the exit.

Why does fail2ban not start on Ubuntu 24.04?#

Ubuntu 24.04 shipped fail2ban 1.0.2, which imports asynchat, a module removed in Python 3.12. The service exits with No module named 'asynchat' and status 255. Install the fixed package 1.0.2-3ubuntu0.1 or newer with sudo apt update && sudo apt install --only-upgrade fail2ban.

Which fail2ban version supports Python 3.12?#

fail2ban 1.1.0 and newer. Version 1.1.0 bundles fallback copies of the asyncore and asynchat modules that Python 3.12 removed, and officially supports Python 3.12 and 3.13. Distribution packages of 1.0.2 on Python 3.12, such as Ubuntu 24.04's, carry their own patch.

How do I see why fail2ban failed to start?#

Run sudo fail2ban-client -t to test the configuration. For runtime failures, run sudo journalctl -u fail2ban -b --no-pager, or start the server in the foreground with sudo fail2ban-server -xf --logtarget=stderr start so every error prints to your terminal.

Will fail2ban restart automatically after fixing the config?#

No. With exit code 255 the unit stays in the failed state. After fixing the config, run sudo systemctl reset-failed fail2ban (optional) and sudo systemctl start fail2ban. Check with sudo fail2ban-client status.