Troubleshooting

This page collects the issues that come up most often. For installation-specific issues, see installation.

Connection issues

My device doesn't appear in the picker

Common causes, in rough order of likelihood:

After any fix, click the picker's refresh (or Ctrl+R).

Picker shows "Unknown device"

The device responded but Companion did not match its handshake. Possibilities:

• Custom firmware — define a custom device profile.
• Different ZeroTrace product than expected — ensure firmware is up to date.
• Genuinely non-ZeroTrace device — Companion is for ZeroTrace hardware.

You can still connect via the terminal for raw access.

Connection drops immediately after connecting

Auto-detection takes forever

Each port probe has a short timeout. Many ports = longer total scan. If you have many virtual COM ports (Bluetooth virtual devices, software-defined ones), the scan can take a few seconds. Accept it, or reduce the number of virtual COM ports.

AI assistant issues

"AI assistant unavailable"

Most common: the model server isn't running.

# Verify Ollama is running
curl http://localhost:11434/api/tags

Should return JSON (even empty {"models":[]}).

If not, start your runner. On macOS the Ollama menu-bar icon shows status. On Linux/Windows, run ollama serve.

"Model not found"

The model name in Companion's settings doesn't match a pulled model. Check ollama list and confirm the exact name.

Responses take forever

Model is too big for your RAM, or you're CPU-only on a model that needs GPU acceleration. Switch to a smaller model — qwen2.5:3b or similar. See models.

Responses are nonsense

Model is too small for the question, or the model has an issue. Try:

• A larger model.
• A different model family.
• Clearing the conversation (Ctrl+L) — sometimes the context has gone off the rails.

Tool calls fail

Some smaller models do not support structured tool calls. Use a tool-calling-capable model — qwen2.5:7b is a safe baseline.

AI privacy concern

If you're worried about what the assistant has seen: the assistant's data stays local with default settings. See AI privacy. Disable AI entirely if your posture requires it.

AirLeak issues

Live view shows zero events

Sessions consume too much disk

Sessions can grow large in busy environments. Mitigations:

• Capture shorter sessions.
• Capture during specific event windows rather than continuously.
• Periodically delete old sessions you no longer need.
• Compress old sessions externally (gzip reduces them 5-10x).

Library merging seems wrong

The library is conservative — it errs toward "two entries that might be the same" over "one entry that's wrong." If you see two entries that should be merged:

• Click both → Merge in the per-device detail.

If you see one entry that should be split, contact support — manual split is not currently exposed in the UI.

Alerts firing constantly

Tune the alert rules. Common patterns:

• Lower the rule's severity if you're seeing too many.
• Add an exception for the specific noise device.
• Disable the rule entirely if it doesn't fit your environment.

Performance issues

Companion uses a lot of RAM

Most RAM usage comes from:

1. Active AirLeak session — millions of events accumulate.
2. Open library — paged from disk but caches recent entries.
3. AI assistant model — multi-gigabyte memory use.

Mitigations:

• Stop unused sessions.
• Restart Companion after long-running multi-hour sessions.
• Use a smaller AI model.

Companion freezes briefly

Usually correlates with:

• A large session export.
• A library re-index.
• A model loading into memory.

Wait it out — these complete in seconds to minutes depending on size.

Charts in the live view are choppy

High event rates in the AirLeak workspace can saturate the rendering. Mitigations:

• Apply filters to reduce visible event count.
• Pause live updates (Space) when reviewing.
• Use the static devices view instead of the live view for heavy review.

Export and data issues

Exported PDF has broken layout

Long unbroken strings (full JWT tokens, very long MAC lists) overflow page width. Mitigations:

• Edit findings to break long content.
• Use Markdown export instead.

CSV export is missing data

CSV is a flat format; deeply nested results get lossy. Use JSON for full fidelity.

Cannot save export

Most common cause: the chosen path is not writable. Try a known-writable location (Documents, Desktop). On macOS, ensure Companion has been granted file-system access.

When to contact support

You've tried the obvious:

• Latest Companion version installed.
• System clock accurate.
• Permissions granted.
• Re-scanned ports / re-installed driver / replaced cable.

…and the issue persists. Contact support with:

• Your operating system and version.
• Companion version (visible in About dialog).
• Connected device model and firmware version.
• Exact error message or behaviour.
• Reproduction steps.

The more specific the reproduction, the faster the response.