Troubleshooting

Symptoms

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

Possible causes

• •Bleep service not running
• •PAC file not configured in system settings
• •Browser or application ignoring PAC configuration

Solutions

1. 1.Verify Bleep is running (check system tray icon - should show green)
2. 2.Bleep automatically configures PAC-based routing for AI traffic only
3. 3.Restart Bleep if the service stopped unexpectedly
4. 4.Note: Only AI traffic (ChatGPT, Claude, etc.) is routed through Bleep - all other traffic goes direct

Symptoms

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

Possible causes

• •App uses custom certificate store
• •App has hardcoded proxy bypass
• •App uses non-HTTP protocols

Solutions

1. 1.Check if app has proxy settings and configure them manually
2. 2.For Electron apps, set environment variables before launching
3. 3.Add app to bypass list if it doesn't need inspection
4. 4.Check app documentation for proxy configuration

Symptoms

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

Possible causes

• •WebSocket traffic being incorrectly inspected
• •Connection timeout during upgrade

Solutions

1. 1.WebSocket connections are passed through by default
2. 2.If issues persist, add the WebSocket domain to 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 already in use error (default proxy port: 8080)

Possible causes

• •Another application using the same proxy port
• •Previous instance didn't shut down cleanly
• •Insufficient permissions

Solutions

1. 1.Check if another service is using the configured proxy port (default: 8080)
2. 2.Change the proxy port in Settings if there's a conflict
3. 3.Restart the Bleep application
4. 4.Run as Administrator if permission errors occur
5. 5.Check Windows Event Viewer 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
• •Proxy 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

• •Proxy was running but stopped on its own
• •System tray shows proxy is off without user action
• •Error message about license or server connectivity
• •Cannot start proxy - error mentions revocation or server unreachable

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

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, the proxy 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

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
• •Entropy-based detection flagging high-entropy strings that are not secrets

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
5. 5.Disable entropy_detection in config if high-entropy strings cause too many false positives

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 selective routing to only intercept AI service traffic
2. 2.Traffic to ChatGPT, Claude, Copilot, and other major AI services is scanned
3. 3.All other traffic (browsing, email, apps) goes direct without inspection
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 proxy 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 proxy 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