Troubleshooting Guide

Troubleshooting Guide

Common issues, diagnostics, and solutions.

---

Session Won't Start

"Port already in use"

Another process is listening on the requested port.

Diagnose:

Availability is evaluated per protocol, and a protocol is a transport plus an address family. Query the same scope the launch check uses, so that what you see is what the launch check saw:

# TCP, IPv4
ss -t -4 -l -n -p | grep :8080

# TCP, IPv6
ss -t -6 -l -n -p | grep :8080

# UDP, IPv4
ss -u -4 -l -n -p | grep :8080

# UDP, IPv6
ss -u -6 -l -n -p | grep :8080

A listener reported in one of these scopes does not occupy the others. tcp4 and tcp6 are independent sockets and can hold the same port number at the same time, which is exactly what dual-stack operation produces.

Fix: Stop the conflicting process, choose a different port, or select a protocol whose scope is free:

socat-manager listen --port 8081
# Or if TCP is taken but UDP is free:
socat-manager listen --port 8080 --proto udp4
# Or if IPv4 is taken but IPv6 is free:
socat-manager listen --port 8080 --proto tcp6

"Permission denied" on Ports Below 1024

Privileged ports require root:

sudo socat-manager listen --port 443

"socat: not found"

socat is not installed or not on PATH:

# Debian/Ubuntu
sudo apt-get install -y socat

# RHEL/Rocky/Alma
sudo dnf install -y socat

# Arch
sudo pacman -S socat

# Verify
which socat
socat -V | head -2

---

Session Started but No Data Captured

Capture Not Enabled

Traffic capture requires the --capture flag:

socat-manager listen --port 8080 --capture

Without --capture, socat runs without the -v verbose flag and no traffic hex dump is produced.

Capture Log Location

Capture logs are in the logs/ directory:

ls logs/capture-*

The filename includes the protocol, port, and timestamp:

logs/capture-tcp4-8080-2026-03-20T14:30:00.log

---

Session Shows in Status but Port Isn't Listening

Stale Session File

The socat process died but the session file wasn't cleaned up.

Diagnose:

socat-manager status --detail
# Check if the PID listed is actually running:
ps -p <PID>

Fix:

socat-manager status --cleanup

This removes session files for processes that are no longer running.

---

Stop Doesn't Work

Session Still Running After stop --all

The 9-step stop sequence handles most cases, but if a process resists SIGKILL (kernel-level hang, zombie state), manual intervention may be needed:

# Check for zombies
ps aux | grep socat | grep -v grep

# Force kill by PID
kill -9 <PID>

# Clean up session files
socat-manager status --cleanup

Wrong Session Stopped

Stopping a session acts only within that session's protocol scope -- its transport and its address family. Stopping a TCP session on port 8080 does not affect a UDP session on port 8080, and stopping an IPv4 session on port 8080 does not affect an IPv6 session on port 8080. Every step of the stop sequence, including the port-based cleanup fallback, derives its scope from the PROTOCOL field of the session file, and the cleanup step signals a process only after confirming through /proc/{pid}/comm that it is socat.

If a session you did not target has stopped, confirm which sessions were actually registered against the port and each one's protocol:

socat-manager status
socat-manager status --detail <SESSION_ID>

A socat process that was not launched through this framework has no session file, is not tracked, and is not a target of the stop sequence. Such processes are reported, not terminated, after stop --all.

---

Dual-Stack Issues

Only One Protocol Starts

If --dual-stack only launches one session, the other protocol's port may already be in use:

socat-manager listen --port 8080 --dual-stack
socat-manager status
# Should show 2 sessions -- check for error messages in logs
cat logs/socat_manager-*.log | tail -20

Stopping One Protocol Leaves the Other Running

This is the intended behavior. A dual-stack launch registers an independent session per protocol, each with its own session ID, and stopping one has no effect on the other. Stop them individually by session ID, or together by port:

socat-manager status                 # Lists both sessions and their protocols
socat-manager stop <SESSION_ID>      # Stops one protocol
socat-manager stop --port 8080       # Stops every session registered on the port

---

Watchdog Issues

Watchdog Keeps Restarting a Session

If the underlying issue isn't resolved (e.g., port conflict), the watchdog will keep restarting and failing. The exponential backoff prevents a tight loop, but the session will cycle.

Diagnose:

# Check session error log
cat logs/session-<SID>-error.log

# Check master log for restart entries
grep "restart" logs/socat_manager-*.log

Fix: Resolve the underlying issue, then restart:

socat-manager stop --name <session-name>
# Fix the issue (free the port, fix network, etc.)
socat-manager listen --port 8080 --watchdog

Watchdog Doesn't Restart After Crash

The .stop signal file may exist from a previous manual stop:

ls sessions/*.stop
# If present, remove it:
rm sessions/<SID>.stop

---

Log Issues

Logs Directory Not Created

The logs/ directory is created automatically on first use. If it's missing, the script may not have write permissions to its directory:

ls -la $(dirname $(which socat-manager))/
# Check for write permission on the installation directory

Fix for make install:

sudo mkdir -p /opt/tools/socat-manager/logs
sudo chown $(whoami) /opt/tools/socat-manager/logs

Logs Growing Too Large

Capture logs can grow quickly under high traffic. Monitor and rotate:

# Check log sizes
du -sh logs/

# Archive old logs
tar czf logs-archive-$(date +%Y%m%d).tar.gz logs/
rm logs/capture-*.log  # Only capture logs, keep session/master logs

---

Installation Issues

make install Fails: "socat not found"

The install target verifies socat is present. Install socat first:

sudo apt-get install -y socat
sudo make install

socat-manager Command Not Found After Install

The wrapper is installed to /usr/local/bin/ by default. Verify it's on your PATH:

echo $PATH | tr ':' '\n' | grep local
ls -la /usr/local/bin/socat-manager

For user-local installs:

make install PREFIX=~/.local/socat-manager BINDIR=~/.local/bin
# Add to PATH if needed:
export PATH="$HOME/.local/bin:$PATH"

make verify Fails

Run make verify after install to diagnose:

sudo make verify

This checks: command on PATH, version output, install directory, runtime directories, socat availability.

---

Getting Help

If your issue isn't covered here:

1. Check the FAQ for common questions
2. Search existing issues
3. Open a bug report with:
   • socat-manager --version output
   • OS and bash version (bash --version)
   • Steps to reproduce
   • Relevant log output from logs/

---

Python-Specific Issues

Python 3.12+ not available

python3 --version
# If below 3.12:
sudo apt-get install python3.12
# Or use pyenv:
curl https://pyenv.run | bash
pyenv install 3.12

ImportError or ModuleNotFoundError

If running without pip install, set the Python path:

PYTHONPATH=src python3 -m socat_manager status
# Or use the standalone runner:
python3 socat-manager.py status

Tests fail with "No module named pytest"

pip install --break-system-packages pytest pytest-cov ruff
# Or use a virtual environment:
make venv && source socat-manager-venv/bin/activate

Watchdog crash loop (BUG-01)

If using an older version, the watchdog may launch duplicate socat processes on already-bound ports. Update to v0.1.0+ which uses the monitor-first architecture.

Symptoms: Rapid restart attempts in logs, "Address already in use" errors. Fix: Update to latest version. The watchdog now monitors existing PIDs instead of launching duplicates.

Menu exits instead of returning after mode execution (BUG-03)

Fixed in v0.1.0. The menu now catches SystemExit from mode handlers.

---

Socat Network Operations Manager · Repository · MIT License