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:

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:

   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:

   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.

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:

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:

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:

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. 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:

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:

# 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:

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

And live flow state:

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).