Skip to content

Troubleshooting

Use this page when the sniffer starts but does not produce the files or behavior you expect.

No connections*.ndjson File Appears

Check these first:

  1. Confirm sniffer.mode: offline
  2. Confirm you did not use --dry-run
  3. Confirm the output path is writable
  4. Confirm packets matched the configured BPF filter
  5. Check the sniffer log file

With rotation enabled, output files are named connections.0.ndjson, connections.1.ndjson, and so on. With rotation disabled, the output file is connections.ndjson.

Example:

tail -100 /var/log/pqc-sniffer/pqc-sniffer.log

Permission Denied on Live Capture

Live capture typically requires root privileges or equivalent packet-capture capabilities.

sudo pqc-sniffer --config /etc/pqc-sniffer/config.yaml --foreground

If you installed manually and still see permission errors when running without sudo, confirm the capture capability is set on the binary:

sudo setcap cap_net_raw+eip /usr/bin/pqc-sniffer

PCAP File Does Not Process

Make sure:

  • the path exists
  • the file is readable
  • the configured capture.interface points to a .pcap, .pcapng, or file:///... input

Config Validation Fails

Run:

sudo pqc-sniffer --config /etc/pqc-sniffer/config.yaml --validate-config

Common causes:

  • non-absolute offline_output.output_file
  • offline_output.output_file contains ..
  • invalid buffer or rotation values
  • missing required sections

Logs Look Fine but Output Is Empty

This usually means one of two things:

  • no traffic matched the BPF filter
  • the capture source did not contain the handshake or protocol events you expected

It can also be expected behavior for unknown plain traffic. Offline mode suppresses generic records when the application protocol remains unknown, including plain DNS/UDP that is not classified as a supported crypto protocol. Narrow the BPF filter to TLS, QUIC, SSH, or known HTTP traffic when validating crypto telemetry.