Troubleshooting

Troubleshooting

Common issues and their solutions.

---

"Permission denied" when running capture mode

macOS:

# One-time setup (persists until reboot)
sudo chmod g+r /dev/bpf*

# Or run with sudo
sudo ocular capture redis 127.0.0.1

Linux:

# Permanent capability (survives reboot)
sudo setcap cap_net_raw+ep $(which ocular)

# Or run with sudo
sudo ocular capture redis 127.0.0.1

---

No events appear in the TUI

Proxy mode:

1. Is your app actually connecting to the Ocular proxy port (not the real service port)?
2. Check: redis-cli -h 127.0.0.1 -p 16379 (proxy port, not 6379)
3. Check the component pane — does the proxy show as connected?

Capture mode:

1. Are you using the correct interface? lo0 for localhost, en0/eth0 for network
2. Is traffic actually flowing? Run tcpdump -i lo0 port 6379 to verify
3. Is the traffic encrypted (SSL)? Capture mode cannot decrypt TLS

---

MySQL: "Lost connection" or auth errors

Ocular auto-strips SSL for MySQL connections. If you see auth issues:

1. Make sure the client connects to the proxy port, not the MySQL port directly
2. Use -h 127.0.0.1 (not localhost — localhost forces Unix socket)
3. If using caching_sha2_password, ensure the MySQL server allows fallback to mysql_native_password

---

Docker: Can't see container-to-container traffic in capture mode

This is expected. Traffic between containers on the same Docker network stays inside the Docker bridge and never reaches the host's network interface.

Solutions:

• Use proxy mode and expose ports to the host (ports: "3306:3306")
• Use proxy mode inside a container (Ocular as a sidecar)

---

Config not found / not loading

Ocular searches for ocular.toml in this order:

1. ./ocular.toml (current directory)
2. $XDG_CONFIG_HOME/ocular/ocular.toml
3. ~/.config/ocular/ocular.toml
4. $HOME/.config/ocular/ocular.toml
5. $SUDO_USER's home (when running under sudo)

Override with: ocular -c /path/to/ocular.toml

---

TUI looks garbled / misaligned

1. Ensure your terminal supports Unicode and 256+ colors
2. Try a different theme: theme = "default" in ocular.toml
3. Resize the terminal window — the TUI redraws on resize
4. If using tmux, ensure default-terminal is set to tmux-256color or screen-256color

---

High CPU usage in capture mode

Capture mode processes every packet on the interface. If there's a lot of non-target traffic:

1. Use a specific BPF filter (Ocular auto-filters by port, but double-check)
2. Use proxy mode instead if possible — it only processes traffic that flows through it
3. On high-traffic production servers, limit capture duration

---

"Address already in use" when starting proxy

The listen port is already bound by another process.

# Find what's using the port
lsof -i :16379

# Use a different listen port
ocular proxy redis 127.0.0.1:6379 -l 127.0.0.1:26379

---

Capture mode sees packets but they're not parsed

This usually means the protocol parser doesn't recognize the wire format. Check:

1. Is the protocol in the Supported Protocols list?
2. Are you using the correct protocol name in config?
3. Is the traffic actually the protocol you think it is? (e.g., Redis on a non-standard port)

Run with debug logging: RUST_LOG=debug ocular capture redis 127.0.0.1