# fail2ban exit code 255: service failed to start

> fail2ban.service exited with status=255/EXCEPTION? Find the real error with journalctl and fail2ban-client -t, then fix missing logs, config typos or Python 3.12.
>
> Source: https://fail2ban.dev/troubleshooting/exit-code-255/ · Updated 2026-10-25 · Checked against fail2ban 1.1.1
> fail2ban.dev is an independent guide, not the official fail2ban project.

`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.

```bash
sudo journalctl -u fail2ban -b --no-pager | tail -40
```

`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?](/troubleshooting/could-not-find-server/).

## 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:

```bash
```

**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:

```bash
sudo tail -n 50 /var/log/fail2ban.log
```

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

```bash
sudo fail2ban-server -xf --logtarget=stderr start
```

**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

```text
```

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

```text
```

- **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:

```bash
python3 --version
apt policy fail2ban      # Debian/Ubuntu
```

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](/troubleshooting/config-errors/).

## Cause 4: unknown filter or action

```text
ERROR   Unable to read the filter 'myapp'
ERROR   Errors in jail 'myapp'. Skipping...
```

## Cause 5: the backend can't load

```text
```

## 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](/troubleshooting/config-errors/).

## Confirm it's fixed

```bash
sudo systemctl reset-failed fail2ban
sudo systemctl start fail2ban
sudo systemctl status fail2ban --no-pager
sudo fail2ban-client status
```

## 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`.