> ## Documentation Index
> Fetch the complete documentation index at: https://quintsecurity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common edge-side issues and how to fix them — extension installs, daemon restarts, backpressure

# Troubleshooting

Issues that come up operating Quint on macOS, ordered roughly by how often they bite.

## NE extension not running

**Symptoms:** `/debug/flows` shows 0 intercepted flows despite traffic to known LLM hosts. `ps aux | grep QuintNetworkExtension` returns empty.

**Check:**

```bash theme={null}
systemextensionsctl list | grep ne-extension
ps aux | grep QuintNetworkExtension | grep -v grep
ifconfig | grep "^utun"   # look for a utun interface created by NE
```

**Common causes:**

1. **Container app not running.** The extension only launches when `QuintAgent.app` is alive and has activated the tunnel. Bounce it:
   ```bash theme={null}
   killall QuintAgent 2>/dev/null; sleep 2; open /Applications/QuintAgent.app
   ```

2. **Extension was killed by macOS resource watchdog.** Pre-v1.0.3 builds had a CPU hot-loop on `EAGAIN` that got SIGKILL'd every \~90s. Check the fix is installed:
   ```bash theme={null}
   strings /Library/SystemExtensions/*/com.quint.security.ne-extension.systemextension/Contents/MacOS/QuintNetworkExtension | grep backpressure
   # Expected: "Write timed out (socket backpressure), dropping frame"
   ```
   If missing, [upgrade](/changelog/v1-0-3).

3. **Code signature invalid.** The extension needs a valid code signature. If `codeSigningID` is empty in a crash report, `launchd` will SIGKILL the extension on startup. Always build via `xcodebuild -configuration Release`, never `swift build` + ad-hoc `codesign --force --sign -`.

## Stale extension bundles stacking up

**Symptoms:** `systemextensionsctl list` shows 5+ entries all marked `[terminated waiting to uninstall on reboot]`. Multiple `activated enabled` entries with different TeamIDs.

**Why:** macOS doesn't actually uninstall extensions until reboot. Development cycles that rebuild + reinstall the `.app` stack up bundles on disk under `/Library/SystemExtensions/<UUID>/`.

**Fix:**

```bash theme={null}
sudo systemextensionsctl uninstall ASS598NHD9 com.quint.security.ne-extension
sudo systemextensionsctl uninstall ASS598NHD9 com.quint.security.extension
# Reboot to actually clear the pending uninstalls
sudo reboot
```

After reboot, confirm you have exactly one active per type:

```bash theme={null}
systemextensionsctl list | grep -c "activated enabled"   # should be 2
ps aux | grep -E "QuintEndpoint|QuintNetwork" | grep -v grep | wc -l   # should be 2
```

## Two extensions active with different TeamIDs

**Symptoms:**

```
*  *  ASS598NHD9  com.quint.security.extension  [activated enabled]
*  *  -           com.quint.security.extension  [activated enabled]
```

The `-` TeamID means ad-hoc signed (no real code signing identity). macOS treats it as a *different* extension from the signed one and allows both to activate simultaneously. Both receive kernel events and both emit to the daemon — you'll see duplicate events.

**Fix:** never use `swift build` + `codesign --force --sign -` for extension installs. Only use `xcodebuild -configuration Release clean build`. Then reboot to clear the ad-hoc leftover.

## Daemon restart killed NE's connection

**Symptoms:** After `Ctrl-C`'ing the daemon and restarting, NE process is still alive but traffic isn't being intercepted. Daemon log shows no `relay:` / `flow START` lines.

**Why:** Before v1.0.3, NE had a tight `EAGAIN` retry loop — when the daemon socket broke, NE burned CPU until macOS killed it. The CPU fix makes NE survive this cleanly, but the socket still needs to reconnect.

**Fix:** bounce the app to force NE to re-establish:

```bash theme={null}
killall QuintAgent; sleep 2; open /Applications/QuintAgent.app
```

A future release will make NE reconnect automatically on daemon restart.

## Claude Code hangs mid-response

**Symptoms:** Response starts streaming, displays fully, then spinner hangs ("Philosophising…" or similar). Next turn also stalls.

**Why (pre-v1.0.3):** The MITM pipeline wasn't emitting chunked framing on SSE responses. On a keep-alive connection, the client had no way to learn the response ended — it just sat waiting.

**Fix:** upgrade to [v1.0.3](/changelog/v1-0-3). Verify `/debug/flows` shows no stuck flows on Bedrock/Anthropic hosts.

## Forwarder overflowing to disk

**Symptoms:** `ls -lh ~/.quint/forwarder-overflow.jsonl` shows a growing file. Daemon log: `forwarder: overflow N events to disk after 5 retries`.

**Why:** The cloud API is unreachable. Either `QUINT_API_URL` is wrong, the deploy token is invalid, or the network is down.

**Check:**

```bash theme={null}
cat /etc/quint/config.yaml   # verify api_url and token
curl -v https://api.quintai.dev/health
curl -v -H "Authorization: Bearer $(grep token /etc/quint/config.yaml | awk '{print $2}')" https://api.quintai.dev/v1/ingest -X POST -d '{"events":[]}'
```

The daemon auto-recovers the overflow file on next successful flush. No action needed beyond restoring reachability.

## Audit DB corruption

**Symptoms:** Daemon startup logs `audit db integrity check: …`, DB file renamed to `quint.db.corrupt-<timestamp>`.

**Why:** Unclean shutdown during heavy writes, filesystem errors, or disk full.

**Fix:** the daemon auto-moves the corrupt file aside and creates a fresh DB on next startup. Historical audit data from the corrupt file can be recovered offline with `sqlite3 quint.db.corrupt-* .recover | sqlite3 recovered.db` if needed.

## Finding a specific session

When you know an action happened but can't find it in the viewer:

```bash theme={null}
# Find sessions with recent activity
sqlite3 ~/.quint/quint.db "
  SELECT process_pid, session_id, COUNT(*) as events, MAX(timestamp) as last_seen
  FROM audit_log
  WHERE process_pid IS NOT NULL
  GROUP BY process_pid
  ORDER BY last_seen DESC
  LIMIT 10
"

# Pull decoded timeline for a specific PID
TOK=$(cat ~/.quint/dashboard-token)
curl -s -H "Authorization: Bearer $TOK" \
  "http://localhost:8080/api/sessions/timeline?pid=59247&limit=200" \
  | python3 -m json.tool
```

The viewer hides sessions that haven't captured any events (opacity-dimmed). Ended sessions appear with `(ended)` tag sorted by most-recent activity — scroll up, they're at the top.

## Ring buffer logs

For anything not captured above, the daemon keeps a 1000-entry ring buffer of its most recent log lines:

```bash theme={null}
TOK=$(cat ~/.quint/dashboard-token)
curl -s -H "Authorization: Bearer $TOK" http://localhost:8080/debug/logs | less
```

And live flow state:

```bash theme={null}
curl -s -H "Authorization: Bearer $TOK" http://localhost:8080/debug/flows | python3 -m json.tool
```

Both require the dashboard token from `~/.quint/dashboard-token` (or `/var/lib/quint/dashboard-token` when installed as root).