Troubleshooting

This guide covers the most common issues and how to resolve them.

Agent Not Connecting / Showing Offline

If your node shows "offline" in the dashboard, the agent is not sending heartbeats. Check these causes in order:

1. Verify the agent is running

If the service is not active, start it:

2. Check the agent logs

Common log messages and what they mean:

3. Verify network connectivity

You should get a 401 response (unauthorized without credentials). If you get a timeout or connection error, check your firewall rules and DNS resolution.

4. Verify the config file

Confirm that api_key, node_uuid, and api_base are set correctly. The api_base should be https://flowtriq.com/api/v1.

5. Reinstall if needed

False Positives and Threshold Tuning

If you are seeing too many false positive incidents, here are the approaches to reduce them:

Increase the PPS Threshold

Go to the node's detail page and increase the PPS Threshold. Start by doubling your current threshold and observe for a few days.

Enable Dynamic Baselines

Dynamic baselines learn your server's normal traffic pattern over time and adjust the detection threshold automatically. Enable this in the agent config:

Configure Service Ports

If your server handles bursty application traffic, configure service ports to prevent legitimate traffic spikes from triggering detection.

Set Minimum Alert Severity

In Settings → Workspace, set Min Alert Severity to "Medium" or "High" to suppress low-severity notifications.

Check the FP Analysis Panel

On each incident detail page, the False Positive Analysis panel shows exactly why the system thinks this might be a false positive. Use this information to tune your configuration.

Mitigation Rules Not Firing

If auto-mitigation is configured but rules are not being applied:

1. Check the rule status: Go to Mitigation and verify your rules are enabled (not paused).
2. Verify severity match: Rules only fire for incidents at or above the configured severity threshold.
3. Check the audit log: Look for mitigation.* events in the Audit Log to see if rules were attempted.
4. Verify node association: If the rule is scoped to specific nodes, confirm the affected node is included.
5. Check pending commands: The incident detail page shows pending mitigation commands and their status (applied, failed, pending).

Notification Delivery Failures

If you are not receiving alerts:

Test the Channel

Go to Alert Channels and click the Test button next to the channel. This sends a synthetic test alert.

Check Notification Log

The notification log (visible in the incident timeline and audit log) shows the delivery status for each alert attempt: sent, failed, or pending.

Common Issues by Channel Type

Check Maintenance Windows

If a maintenance window is active for the affected node, notifications are suppressed by design. Check Maintenance for active windows.

Check Notification Preferences

In Settings → Account → Notification Preferences, verify you have not muted the severity level or enabled quiet hours.

Check Min Alert Severity

In Settings → Workspace, the Min Alert Severity setting suppresses alerts below the configured level.

PCAP Not Capturing

If incidents do not have PCAP data attached:

1. Check pcap_enabled: Verify "pcap_enabled": true in /etc/ftagent/config.json.
2. Check limited mode: If the agent runs with --limited, PCAP is disabled.
3. Check dependencies:
   • For scapy mode: pip show scapy should show the package is installed.
   • For tcpdump mode: which tcpdump should return a path.
4. Check disk space: Verify the PCAP directory has sufficient space: df -h /var/lib/ftagent/pcaps
5. Check permissions: The agent must run as root (or with CAP_NET_RAW) for packet capture.
6. Check logs: Look for PCAP-related errors in journalctl -u ftagent.

Dashboard Access Issues

Cannot Log In

• Wrong password: Use the "Forgot password" link on the login page to reset.
• Account deleted: If you see "deleted" in the URL, your account was deleted. You need to sign up again.
• IP allowlist: If the workspace owner configured an IP allowlist and your IP is not on it, you will be blocked. Contact the workspace owner.

Dashboard is Slow

• Check if you have many nodes (100+) or many incidents. The overview page loads all active nodes at once.
• Try filtering by time range (use 24h instead of 90d).
• Clear your browser cache and try again.

Common Error Messages

Getting More Help

• Agent debug mode: Run sudo ftagent --debug for verbose output
• Agent version: Run ftagent --version to check the installed version
• Agent update: Run sudo ftagent --update to check for and install updates
• Discord community: Join at discord.gg/SsTWMYuyGG
• Contact support: flowtriq.com/contact