| Symptom | What to check |
|---|---|
| Fail2Ban command denied/unavailable, timeout, or parse failure | Read the degraded detail; verify Fail2Ban availability, actual client path, and narrowly scoped noninteractive sudo permission. Last-good data is retained; it is not current success. |
| Missing or unreadable report history | Verify configured file paths and current-user read access, including rotations. At least the current log or its plain .1 rotation must exist; gzip history alone is insufficient. Disappearing rotations are skipped; unreadable files can fail collection. Empty history does not prove there were no bans. |
| GeoIP unavailable or reader failure | Inspect diagnostics/status for independent Country/ASN sources and reader errors; check the same user/XDG environment and file readability. Unmapped is a different state. |
| GeoIP stale | Local age exceeds 62 days; readable data remains usable. Choose an explicit update if desired. |
| Refresh/GeoIP operation already in progress | The request was not queued or started again. Retry after the operation finishes; the footer indicator may linger briefly after completion. A pending period label does not change the committed report. |
| GeoIP update failure | Read the latest outcome; usable active data is preserved. Check the reported network/storage/validation error before choosing another explicit attempt. |
| Registration/RDNS request failed | Read the outcome: check host DNS configuration for resolver-unavailable, DNS reachability for timeout/dns-failure, and outbound RDAP access for rdap-unavailable. no-result means no PTR answer; not-global skips registration traffic. A rate limit requires waiting before another explicit request. |
| Coverage partial/unavailable | Read source limitations for owner/journal/config/log access. Optional evidence failure is not proof of no exposure or complete protection. |
| Unexpected old dashboard or unrecognized GeoIP command | Use command -v offenders and Bash type -a offenders to check whether the retained standalone executable shadows pipx. |
There is no generic user configuration file. Periods are fixed runtime choices; GeoIP data and automatic policy are user-owned XDG state.
Registration/RDNS dependencies are installed with Offenders. A missing Python import indicates an incomplete installation: reinstall the package in its pipx environment. A temporary request failure does not disable either action.
Check that the destination root (default ~/offenders-exports/) is writable by
the account running Offenders, parent directories are traversable, and the volume
has free space. The CLI can choose a writable root with --output-dir; existing
root permissions are preserved. Avoid running as root merely to export.
Exports require Linux atomic no-replace rename support in libc, the kernel, and
the destination filesystem. Unsupported filesystems fail rather than overwrite
existing exports. Try a local Linux filesystem if publication is unsupported.
A handled write/publication failure removes temporary staging; completed exports
remain untouched. An abrupt process termination may leave a hidden
.offenders-export-* staging directory, which is not a completed export.
The TUI retains the committed report on failure, so it can be retried. If no
report has succeeded yet, resolve the report acquisition error first.