Troubleshooting - SVLive Agent macOS
Use the troubleshooting information below to help you quickly diagnose issues.
- Quick Diagnostics
- Common Error Messages and Solutions
- App Not Starting
- Location Permission Issues
- WiFi Scanning Issues
- LaunchAgent Issues
- Configuration Issues
- Installation/Upgrade Issues
- Network Connectivity Issues
- Performance Issues
- Log Files and Diagnostics
- Complete Reinstall
- Contact Support for Additional Help
Quick Diagnostics
Run these commands to get a quick overview of the app's status:
# Check if app is running ps aux | grep SVLiveAgent | grep -v grep # Check LaunchAgent status launchctl list | grep com.serraview.sps # Check location permission sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \ "SELECT service, client, auth_value FROM access WHERE client LIKE '%serraview%'" # View recent logs (LaunchAgent stdout + structured app log) tail -50 /tmp/svliveagent.log tail -50 ~/Library/Application\ Support/SVLiveAgent/SVLiveAgent.log # Check configuration cat "/Library/Application Support/SVLiveAgent/sps.ini"
Common Error Messages and Solutions
| Error Message | Cause | Solution |
|---|---|---|
| "Operation not permitted" |
Missing Location Services permission |
Grant permission via System Settings. |
|
"Connection refused" |
Config endpoint unreachable |
Check network, verify endpoint URL. |
|
"Invalid configuration" |
Malformed config file | Fix sps.ini format. |
|
"Failed to load LaunchAgent" |
Plist syntax error or permissions | Validate plist, fix permissions. |
|
"App quit unexpectedly" |
App crash | Check crash logs, verify config. |
|
"No WiFi interface found" |
Mac Mini/Desktop without WiFi | Expected behavior, app still functions. |
|
"Certificate verification failed" |
SSL/TLS issue | Check system time, update macOS. |
App Not Starting
Symptom: App doesn't launch after installation
| Checks | Solution |
|---|---|
|
Verify app is installed
|
If missing, reinstall the PKG. |
|
Check if LaunchAgent is loaded
You should see a PID and status. |
If not loaded, manually load it:
|
|
Check for errors in logs
|
Look for:
|
|
Try launching manually
|
If app launches manually but not via LaunchAgent, check LaunchAgent plist file:
Verify:
|
|
Symptom: App keeps crashing Check crash logs: # System crash logs
# View most recent crash
Common causes:
|
Fix the underlying issue, then restart:
|
Location Permission Issues
Symptom: WiFi access points not detected
| Checks | Solution |
|---|---|
|
Verify Location Services permission # Check TCC database
Expected:
|
Solution: If permission is denied or missing: Via System Settings:
Reset and re-prompt:
|
Symptom: Permission prompt doesn't appear on first launch
| Cause | Solution |
|---|---|
| The app needs to actually USE location services to trigger the prompt. |
|
Symptom: Custom permission alert appears twice
| Cause | Solution |
|---|---|
| Race condition between permission check and delegate callback. |
This is fixed in current version. If still occurring, restart the app:
|
WiFi Scanning Issues
Symptom: No WiFi networks detected on Mac Mini/Desktop
| Cause | Solution |
|---|---|
|
Device has no built-in WiFi adapter. Expected behavior: App will report an empty wireless adapter with placeholder MAC 00:00:00:00:00:00. Verify:
|
This is normal for Mac Mini and desktops without WiFi. The app will still function and report presence based on other signals (screen lock, idle time, etc.). |
Symptom: WiFi scanning fails with "Operation not permitted"
| Cause | Solution |
|---|---|
| Missing Location Services permission. | Grant Location Services permission (see Location Permission Issues) |
Symptom: WiFi scanning slow or timing out
| Checks | Solution |
|---|---|
|
Network adapter health
|
|
|
Check if the interface is up
|
If the interface is down, then enable it:
|
LaunchAgent Issues
Symptom: LaunchAgent not loading on login
| Checks | Solution |
|---|---|
|
Verify plist file exists
|
Fix permissions if incorrect:
|
|
Check 2: Validate plist syntax
Expected: OK |
Same as above |
|
Check permissions
Expected:
|
Same as above |
Symptom: LaunchAgent loaded but app not running
| Checks | Solution |
|---|---|
|
Check LaunchAgent status:
Look for:
Inspect the LaunchAgent job (paths, state, last exit):
On recent macOS, |
Check logs for crash reason, fix the issue, then reload:
|
Symptom: KeepAlive not working (app doesn't restart after quit)
| Check | Solution |
|---|---|
|
Verify KeepAlive setting:
Expected:
|
If
|
Configuration Issues
Symptom: App starts but doesn't connect to backend
| Checks | Solution |
|---|---|
|
Verify config file exists
|
Update config endpoint:
|
|
Verify config-endpoint is set
Expected: Valid URL, not placeholder. |
Same as above. |
Symptom: "Invalid configuration" error in logs
| Check | Solution |
|---|---|
|
Check configuration format:
Verify:
|
Fix format, then restart:
|
Installation/Upgrade Issues
Symptom: Installation hangs during PKG install
| Checks | Solution |
|---|---|
|
Possible causes:
|
Kill old app:
|
|
Check disk space:
|
Retry installation:
|
Symptom: After upgrade, old version still running
| Cause | Solution |
|---|---|
|
Race condition where old LaunchAgent restarted old app before the upgrade was completed. |
|
Symptom: "Package is damaged" error during install
| Cause | Solution |
|---|---|
|
Code signature issue or corrupted download. Check signature:
|
|
Network Connectivity Issues
Symptom: App can't reach config endpoint
| Checks | Solution |
|---|---|
|
Check 1: Test network connectivity
Expected: HTTP 200 or similar success code. |
If blocked, allow:
|
|
Check firewall/proxy settings
|
Same as above. |
Symptom: SSL/TLS certificate errors
| Checks | Solution |
|---|---|
|
Check logs for certificate errors:
|
|
Performance Issues
Symptom: High CPU usage
| Check | Solution |
|---|---|
|
Check what's consuming CPU:
Common causes:
|
|
Symptom: High memory usage
| Check | Solution |
|---|---|
|
Check memory:
If memory >200MB, potential memory leak. |
|
Log Files and Diagnostics
Log File Locations
| Log Type | Location | Purpose |
|---|---|---|
| Standard Output | /tmp/svliveagent.log |
LaunchAgent stdout (includes many print() lines, e.g. WiFi/location status from WiFiService) |
| Standard Error | /tmp/svliveagent.error.log |
LaunchAgent stderr |
| App file log | ~/Library/Application Support/SVLiveAgent/SVLiveAgent.log |
Structured logs from LoggingService (HTTP/TLS errors, configuration, throttled server errors, shutdown path, etc.) |
| System Logs | log show --predicate 'process == "SVLiveAgent"' |
Unified logging / Console |
| Crash Reports | ~/Library/Logs/DiagnosticReports/SVLiveAgent*.crash |
Crash dumps |
Viewing Logs
Recent logs:
tail -50 /tmp/svliveagent.log
Real-time monitoring:
tail -f /tmp/svliveagent.log
Search for errors (check both stdout and the structured log):
grep -i "error\|fail\|denied" /tmp/svliveagent.loggrep -i "error\|fail\|denied" ~/Library/Application\ Support/SVLiveAgent/SVLiveAgent.log
Search for location permission events (printed to stdout → /tmp when running under LaunchAgent):
grep "Location permission" /tmp/svliveagent.log
Search for network events:
grep -i "wifi\|network\|scan" /tmp/svliveagent.loggrep -i "wifi\|network" ~/Library/Application\ Support/SVLiveAgent/SVLiveAgent.log
System logs (last hour):
log show --predicate 'process == "SVLiveAgent"' --last 1h
Collect Diagnostic Information
Run this to collect full diagnostic info:
#!/bin/bash
# SVLiveAgent Diagnostics Collection Script
OUTPUT_FILE="svliveagent-diagnostics-$(date +%Y%m%d-%H%M%S).txt"
{
echo "======================================"
echo "SVLiveAgent Diagnostics"
echo "Date: $(date)"
echo "======================================"
echo ""
echo "=== System Info ==="
sw_vers
echo ""
echo "=== App Installation ==="
ls -la /Applications/SVLiveAgent.app
echo ""
echo "=== App Version ==="
defaults read /Applications/SVLiveAgent.app/Contents/Info.plist CFBundleShortVersionString 2>/dev/null || echo "Version not available"
echo ""
echo "=== Process Status ==="
ps aux | grep SVLiveAgent | grep -v grep
echo ""
echo "=== LaunchAgent Status ==="
launchctl list | grep com.serraview.sps
echo ""
echo "=== LaunchAgent Plist ==="
cat /Library/LaunchAgents/com.serraview.sps.plist 2>/dev/null || echo "Plist not found"
echo ""
echo "=== Configuration ==="
cat "/Library/Application Support/SVLiveAgent/sps.ini" 2>/dev/null || echo "Config not found"
echo ""
echo "=== Location Permission ==="
sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
"SELECT service, client, auth_value FROM access WHERE client LIKE '%serraview%'" 2>/dev/null || echo "TCC check failed"
echo ""
echo "=== WiFi Interface ==="
system_profiler SPAirPortDataType 2>/dev/null | head -20
echo ""
echo "=== Recent Logs (last 100 lines) ==="
tail -100 /tmp/svliveagent.log 2>/dev/null || echo "Log file not found"
echo ""
echo "=== Structured app log (last 100 lines) ==="
tail -100 ~/Library/Application\ Support/SVLiveAgent/SVLiveAgent.log 2>/dev/null || echo "SVLiveAgent.log not found"
echo ""
echo "=== Recent Errors ==="
tail -50 /tmp/svliveagent.error.log 2>/dev/null || echo "Error log not found"
echo ""
echo "=== Recent Crashes ==="
ls -lt ~/Library/Logs/DiagnosticReports/SVLiveAgent*.crash 2>/dev/null | head -5 || echo "No crash reports"
echo ""
} > "$OUTPUT_FILE"
echo "Diagnostics saved to: $OUTPUT_FILE"
Save as collect-diagnostics.sh, make executable, and run:
chmod +x collect-diagnostics.sh./collect-diagnostics.sh
Complete Reinstall
If all else fails, perform a complete clean reinstall:
1. Complete Uninstall
#!/bin/bash # Complete SVLiveAgent Uninstall echo "Uninstalling SVLiveAgent..." # Stop and unload LaunchAgent launchctl bootout gui/$(id -u) /Library/LaunchAgents/com.serraview.sps.plist 2>/dev/null sudo launchctl bootout system /Library/LaunchAgents/com.serraview.sps.plist 2>/dev/null # Kill any running instances killall -9 SVLiveAgent 2>/dev/null # Remove LaunchAgent sudo rm -f /Library/LaunchAgents/com.serraview.sps.plist # Remove application sudo rm -rf /Applications/SVLiveAgent.app # Remove configuration and data sudo rm -rf "/Library/Application Support/SVLiveAgent" sudo rm -rf "/Library/Application Support/Condeco" # Remove logs rm -f /tmp/svliveagent.log rm -f /tmp/svliveagent.error.log # Remove package receipts sudo pkgutil --forget com.serraview.sps 2>/dev/null sudo pkgutil --forget com.serraview.SVLiveAgentSwift 2>/dev/null # Reset permissions (optional - only if you want to be prompted again) tccutil reset Location com.serraview.sps 2>/dev/null echo " Uninstall complete"
2. Clean Install
# Wait a moment for system to stabilize sleep 5 # Install new PKG sudo installer -pkg SVLiveAgent.pkg -target / # Or use the installer script sudo bash svliveagent-installer.sh PKGFILE=SVLiveAgent.pkg CONFIGAPIADDRESS=<your-endpoint> # Verify installation sleep 3 ps aux | grep SVLiveAgent | grep -v grep
3. Verify Installation
# Check app running pgrep SVLiveAgent # Check LaunchAgent loaded launchctl list | grep com.serraview.sps # Check logs tail -50 /tmp/svliveagent.log # Check location permission open "x-apple.systempreferences:com.apple.preference.security?Privacy_LocationServices"
Contact Support for Additional Help
If you have tried all troubleshooting steps and still have issues:
- Collect diagnostics using the script above.
- Check logs for specific error messages
- Document:
- macOS version (sw_vers)
- Device type (MacBook/Mac Mini/iMac)
- Exact error messages
- Steps to reproduce
- Contact our Support team and provide the collected information.