Troubleshooting

Most “problems” with Kickoutchi are actually the OS being cautious. Here’s how to read the common ones.

A port shows in another tool but not in Kickoutchi

Kickoutchi lists listening TCP sockets and bound UDP sockets • the socket states that occupy a local port. It doesn’t list established/outbound connections, so a port you see in a connection-oriented tool may simply not be a listener. It also uses native collectors rather than parsing ss, netstat, or lsof, so output can differ from those tools by design.

Process metadata is missing (shows -)

The socket is visible but some process metadata wasn’t readable • usually because the process belongs to another user. The row still appears, tagged with partial permission so the blank is explained rather than hidden. Re-run with higher privileges to fill it in.

Permission denied when killing

You don’t have the rights to signal that process (exit 4). On Linux/macOS, try sudo; on Windows, use an elevated terminal. If a --port target has no readable owning PID, Kickoutchi reports permission denied rather than guessing.

A protected process asks for stronger confirmation

That’s protection working. Type the PID or the process name to confirm. If a process is protected that you’d rather treat normally, adjust your protected_processes • but the built-in safety names are there for good reasons.

kill --port says the target is ambiguous

Two or more PIDs own that port, so Kickoutchi refuses to guess. It prints the candidates; re-run with --pid and the one you mean.

Docker-owned port details are partial or unavailable

Docker context is enrichment, shown when the Docker CLI is available • it’s never required for normal port listing. Without the Docker CLI, you’ll still see the port and process, just not the container mapping.

Linux: kernel too old for pidfd termination

Listing ports works on older kernels, but safe pidfd-based termination needs Linux 5.3+. On a newer kernel, the signal is tied to a process handle so a recycled PID can’t be hit by mistake.

Windows: some processes need an elevated terminal

Higher-privilege processes can hide metadata or reject termination from a normal shell. Re-open your terminal as administrator and try again.

macOS: process identity changed before termination

macOS has no pidfd, so Kickoutchi re-checks the process identity right before signalling. If the PID was reused by a different process between your confirmation and the signal, it refuses and sends nothing. Re-list and try again.

Linux/macOS tree/group kill says it thawed everything

That means the scoped kill hit a safety refusal after freezing began: permission denied, identity drift, protected descendant, incomplete metadata, cap overflow, or a sweep that would not converge. Kickoutchi sent SIGCONT to every member it had stopped and sent no termination signal.

Windows tree kill reports incomplete metadata or partial containment

Windows tree kill has no SIGSTOP equivalent. It preflights before the Job Object commit and fails closed if missing creation-time metadata could hide a descendant. After commit, it reports partial containment, fallback termination, and not-terminated PIDs instead of calling the kill fully successful.

Windows: --group or TUI t/T is unavailable

That’s expected. Windows supports read-only inspect and CLI --tree, but --group is a POSIX process-group feature and the Windows TUI still omits the tree keys. If inspect or CLI --tree is unknown on Windows, run kick --version and update to the latest release.

The TUI says “Terminal too small”

The table needs at least 80×20. Resize the window (or zoom out your terminal font) and the UI comes back.

kickoutchi-update is missing

The updater shipped with the installer starting at a certain release. If you installed earlier, rerun the latest installer once to opt in • future upgrades can then use kickoutchi-update.