Troubleshooting

Symptoms

• •AI requests bypass Bleep entirely
• •Dashboard shows no requests to ChatGPT, Claude, etc.
• •Sensitive data not being detected in AI prompts

Possible causes

• •Bleep service not running
• •System DNS not pointing to 127.0.0.1
• •Another DNS resolver overriding Bleep's DNS settings

Solutions

1. 1.Verify Bleep is running (check system tray / menu bar icon - should show green)
2. 2.Windows/Linux: Bleep automatically sets system DNS to 127.0.0.1 to redirect AI traffic
3. 3.Windows/Linux: restart Bleep if the service stopped unexpectedly - DNS settings are auto-restored by the dead-man's switch
4. 4.macOS: Bleep uses an Apple System Extension (not DNS). Open System Settings → General → Login Items & Extensions and confirm the Bleep network extension is enabled and allowed; the DNS checks below do not apply on macOS
5. 5.Note: Only AI domain traffic is intercepted - all other traffic passes through untouched

Symptoms

• •One app fails while others work fine
• •Application shows certificate errors
• •Connection refused or timeout errors

Possible causes

• •App uses custom certificate store that doesn't include Bleep's CA
• •App has hardcoded DNS resolver bypassing system DNS
• •App pins specific certificates (certificate pinning)

Solutions

1. 1.Install the Bleep CA certificate in the app's certificate store
2. 2.For Node.js apps, set NODE_EXTRA_CA_CERTS to the Bleep CA cert path
3. 3.Add the domain to the bypass list if the app doesn't need inspection
4. 4.Check if the app uses DNS-over-HTTPS (DoH) which bypasses system DNS - disable it in the app settings

Symptoms

• •Real-time features not working
• •Chat applications disconnecting
• •WebSocket upgrade failed errors

Possible causes

• •WebSocket traffic being incorrectly inspected
• •Connection timeout during TLS handshake

Solutions

1. 1.WebSocket connections are passed through by default
2. 2.If issues persist, add the WebSocket domain to the bypass list
3. 3.Ensure the destination uses wss:// (secure WebSocket)

Symptoms

• •Endpoint app shows "Server unreachable" or connection timeout
• •Enrollment fails from another PC on the same network
• •Dashboard works on the server PC but not from other devices

Possible causes

• •Admin server is bound to localhost (127.0.0.1) instead of all interfaces
• •Firewall blocking the admin server port on the server machine
• •Endpoint is configured with localhost instead of the server's LAN IP

Solutions

1. 1.Start the admin server with --bind 0.0.0.0 (or set BLEEP_BIND_HOST=0.0.0.0) to accept LAN connections
2. 2.Allow the admin port (default: 8081) through the server machine's firewall
3. 3.On endpoint devices, use the server's LAN IP (e.g. http://192.168.1.50:8081) instead of localhost
4. 4.Verify connectivity: from the endpoint PC, open the server URL in a browser

Symptoms

• •Desktop app shows "Service not running"
• •System tray icon missing
• •Port 53 (DNS) already in use error

Possible causes

• •Another DNS resolver using port 53 (e.g., systemd-resolved on Linux, Pi-hole, dnsmasq)
• •Previous instance didn't shut down cleanly
• •Insufficient permissions (service requires admin/root to bind port 53)

Solutions

1. 1.On Linux: disable systemd-resolved (sudo systemctl disable --now systemd-resolved) or configure it to free port 53
2. 2.Check if another DNS service is using port 53: netstat -tlnp | grep :53 (Linux) or netstat -an | findstr :53 (Windows)
3. 3.Restart the Bleep application
4. 4.Run as Administrator if permission errors occur - the service needs elevated privileges to manage DNS
5. 5.Check Windows Event Viewer or journalctl -u bleep for detailed error logs

Symptoms

• •Browser shows "Your connection is not private" error
• •Applications fail to connect with certificate errors
• •ERR_CERT_AUTHORITY_INVALID in Chrome

Possible causes

• •CA certificate not installed in system trust store
• •Certificate was installed for wrong user
• •Application uses its own certificate store (Firefox, Java)

Solutions

1. 1.Open Bleep Settings → Certificates → Click "Install CA Certificate"
2. 2.For Firefox: Go to Settings → Privacy & Security → Certificates → Import the CA cert
3. 3.For Java apps: Use keytool to import the certificate into the Java keystore
4. 4.Restart the application after installing the certificate

Symptoms

• •"Failed to connect to license server" error
• •"License not found" error
• •"License expired" error
• •Protection starts in limited mode

Possible causes

• •Invalid or expired license key
• •Network connectivity issues
• •Firewall blocking license server
• •License key copied incorrectly

Solutions

1. 1.Verify your license key at Dashboard → Licenses
2. 2.Ensure internet connectivity to *.supabase.co
3. 3.Check if firewall allows outbound HTTPS (port 443)
4. 4.Copy the license key again, ensuring no extra spaces
5. 5.Contact support if your license was recently purchased

Symptoms

• •Service was running but stopped on its own
• •System tray shows protection is off without user action
• •Error message about license or server connectivity
• •Cannot start service - error mentions revocation or server unreachable
• •DNS settings were automatically restored after a crash (dead-man's switch)

Possible causes

• •Admin server license expired or was revoked
• •Device seat was revoked by an administrator
• •Admin server has been unreachable for over 72 hours
• •Instance conflict - the same license was bound to a different server
• •Service crashed - DNS is auto-restored by the dead-man's switch to prevent lockout

Solutions

1. 1.Check if the admin server license is still valid in the cloud dashboard
2. 2.Contact your administrator to verify your device seat is still active
3. 3.Ensure the admin server is online and reachable from this device
4. 4.If the server was offline, protection will resume automatically once connectivity is restored within the 72-hour grace period
5. 5.For instance conflicts, use the rebind option to transfer the license to the current server
6. 6.If the service crashed, restart it - DNS will be reconfigured automatically

Symptoms

• •Legitimate content being flagged
• •Non-sensitive data detected as sensitive
• •Requests being blocked unnecessarily

Possible causes

• •Detection patterns too broad
• •Content matching pattern by coincidence
• •Generic patterns like "key" or "token" matching non-sensitive data

Solutions

1. 1.Add false positive domains/patterns to allowlist
2. 2.Refine custom patterns to be more specific
3. 3.Use context-aware patterns that check surrounding content
4. 4.Switch from "block" to "redact" mode for less-critical patterns

Symptoms

• •Only AI services appear in the dashboard
• •Regular websites don't show up in logs
• •Non-AI traffic seems to bypass Bleep

Possible causes

• •This is expected behavior - Bleep only monitors AI traffic

Solutions

1. 1.Bleep uses DNS redirect to selectively intercept only AI service traffic
2. 2.AI domain DNS queries resolve to a local address where Bleep terminates TLS and inspects traffic
3. 3.All other DNS queries are forwarded to the upstream resolver and traffic flows directly
4. 4.This design ensures minimal footprint and no interference with other applications

Symptoms

• •Uploaded images with visible API keys are not detected
• •PDFs or Office documents (DOCX, XLSX, PPTX) with secrets pass through undetected
• •File scanning appears to have no effect
• •OCR results are empty or inaccurate

Possible causes

• •File scanning is disabled in configuration (image_scanning: false)
• •OCR engine failed to initialize (check logs for warnings)
• •Image is too large (over 5 MB) or too small
• •PDF or document is too large (over 50 MB)
• •Low-resolution image or blurry text that OCR cannot read
• •Corrupt or password-protected Office document / PDF

Solutions

1. 1.Verify file scanning is enabled: check config.yaml for image_scanning: true (default: true)
2. 2.File scanning works on Windows, macOS, and Linux - check service logs for initialization errors
3. 3.Ensure images are under 5 MB and contain clear, readable text. PDFs and documents can be up to 50 MB.
4. 4.For images, try with a higher-resolution screenshot - OCR works best with sharp, high-contrast text
5. 5.Supported document formats: DOCX, XLSX, PPTX, RTF, PDF, and plain text files (.py, .js, .txt, .csv, etc.)
6. 6.Check service logs for OCR or document extraction warnings

Symptoms

• •AI services (ChatGPT, Claude) responding slowly
• •Timeouts when sending prompts
• •Noticeable delay in AI responses

Possible causes

• •Complex detection patterns running on large prompts
• •Large response bodies being scanned
• •Resource constraints on the system

Solutions

1. 1.Note: Bleep only scans AI traffic - regular browsing is not affected
2. 2.Reduce the number of active detection patterns if latency is high
3. 3.Check system resources (CPU/RAM) during AI requests
4. 4.Large prompts with lots of code may take longer to scan