Troubleshooting Guide

Troubleshooting Guide

Common issues organized by category with root cause analysis and solutions.

Installation

Issue	Root Cause	Solution
pip3 install fails "Multiple top-level packages"	setuptools auto-discovers data/	Ensure pyproject.toml has [tool.setuptools.packages.find] with explicit include/exclude
pip3 install license deprecation	Old license = {text = "MIT"} format	Use SPDX: license = "MIT"
SyntaxError on type hints	Python < 3.12	Upgrade Python: python3 --version must show 3.12+
venv creation fails	venv module not installed	sudo apt install python3-venv (Debian) or sudo dnf install python3-venv (RHEL)
"ModuleNotFoundError: apotropaios"	Not in project root or not installed	Use python3 apotropaios.py from project root, or pip3 install .

Runtime

Issue	Root Cause	Solution
"No backend selected"	No firewall installed or detected	Install a firewall or use --backend NAME
"Permission denied"	Not running as root	Use sudo python3 apotropaios.py COMMAND
"Protocol not supported"	Container/VM missing kernel modules	sudo modprobe ip_tables iptable_filter nf_tables
No visible output	Default console is WARNING	Use --log-level info or --log-level debug
--log-level not recognized after command	Outdated version	Update: global options are now position-independent
Slow startup	5 backend probes with timeouts	Normal; use --backend NAME to skip auto-detection

Backend-Specific

Issue	Backend	Solution
"FirewallD is not running"	firewalld	sudo systemctl start firewalld && sudo systemctl enable firewalld
"nft: command not found"	nftables	Install: sudo apt install nftables
"Set in use by kernel component"	ipset	Apotropaios removes iptables refs first; manual: iptables -D INPUT <line>
Reset doesn't clear all zones	firewalld	Ensure latest version -- reset now iterates ALL zones
Auto-selects wrong backend	any	Override: --backend firewalld

Rule Management

Issue	Root Cause	Solution
Rule created but not in system-rules	Backend apply failed; rule still indexed	Check log file for error; remove-rule <UUID> to clean
"Rule not found" on remove	UUID not in index	list-rules to see available UUIDs
Temporary rule not expiring	ExpiryMonitor only runs in interactive mode	Use interactive menu for temp rules
Import validation fails	Missing fields or invalid values	Use --dry-run to see which rules fail
"Cannot combine multiple terminal actions"	drop,accept has two terminals	Use log,drop or log,accept (one non-terminal + one terminal)

Backup and Logging

Issue	Root Cause	Solution
Checksum verification fails	Archive modified/corrupted	Regenerate: sha256sum backup.tar.gz > backup.tar.gz.sha256
Cannot delete immutable snapshot	chattr +i set	Remove attribute: sudo chattr -i <file>
Log file unreadable	0o600 perms, root-owned	Read with sudo: sudo cat data/logs/*.log
Sensitive data in logs	Field name not in sanitizer list	Add to _SENSITIVE_KEYS in core/logging.py

Diagnostic Commands

sudo python3 apotropaios.py detect --log-level trace    # Maximum detail
python3 --version                                         # Check Python
which iptables nft firewall-cmd ufw ipset                # Check backends
make check-deps                                           # All dependencies
sudo cat $(ls -t data/logs/*.log | head -1)              # Last log file
make metrics                                              # Project stats

Install or Update Appears to Hang

Package operations run fully non-interactively. stdin is closed on every package-manager invocation so no prompt can block one (dpkg configuration-file questions get the safe keep-existing default), waits on a concurrent package manager are bounded by a 60-second dpkg lock timeout, and the whole operation is bounded by the 300-second long-operation timeout, after which it fails with a timeout error. A status line naming the package, manager, and timeout prints at the start; because package-manager output is captured, silence after that line during a large download is normal.

Ctrl+C aborts the operation immediately. From the interactive menu, control returns to the Install & Update submenu; from the CLI, the process exits with status 130. On a reported timeout, check mirror reachability and whether another package manager holds the dpkg or dnf lock.

Interrupt Behavior (Ctrl+C)

Inside the interactive menu, Ctrl+C aborts the operation or prompt in progress and returns to the menu; it never terminates the application. In headless CLI use, Ctrl+C executes the cleanup stack and exits with status 130. SIGTERM and SIGHUP always terminate through the cleanup stack.