Connectivity Troubleshooting

This guide helps you resolve connectivity and real-time update issues in CrystalQore. When messages are delayed, presence doesn't update, or live data stops refreshing, the cause is often WebSocket connectivity, browser behavior, or network restrictions.

Common Issues

---

Solutions

1. Check Your Internet Connection

• Verify connectivity — Open another site or run a speed test
• Stability — Wi‑Fi can drop; try Ethernet if possible
• VPN — Some VPNs block or throttle WebSockets; try without VPN
• Mobile hotspot — Test from a different network to rule out your usual connection

2. WebSocket and SSE Connections

CrystalQore uses WebSockets (and possibly Server-Sent Events) for real-time updates:

• Chat messages — Delivered over WebSocket
• Presence — Status updates via WebSocket
• Call state — Real-time call events
• Dashboard — Live stats and activity

If WebSockets are blocked or fail:

• Messages may be delayed until you refresh
• Presence may show stale status
• You may see "Reconnecting" or "Disconnected" in the UI

3. Browser Compatibility

Recommended browsers:

• Chrome — Full support
• Firefox — Full support
• Edge — Full support
• Safari — Supported but has known limitations with WebSockets in some versions

4. Clear Browser Cache

Stale cache can cause:

• Outdated JavaScript that doesn't handle reconnection properly
• Cached service workers interfering with connections
• Old assets leading to inconsistent behavior

Steps:

1. Open browser settings
2. Clear cache and cookies for the CrystalQore site (or clear all)
3. Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
4. Log in again

5. Corporate Firewall or Proxy

Corporate networks often restrict WebSocket and non-HTTP traffic:

• WebSocket — Uses HTTP upgrade; some proxies block or break it
• SSE — Long-lived HTTP; some proxies close idle connections early
• Ports — WebSocket typically uses 80 (HTTP) or 443 (HTTPS); same as web traffic

What to check:

• Does it work from home or mobile data? If yes, the issue is likely corporate network
• Contact IT to allow WebSocket connections to your CrystalQore URL
• Ask about proxy configuration for WebSocket (e.g., Upgrade: websocket, Connection: Upgrade)
• Some organizations require a PAC file or proxy exceptions for SaaS apps

6. Extensions and Privacy Tools

Browser extensions can interfere with real-time connections:

• Ad blockers — May block WebSocket endpoints or domains
• Privacy extensions — Can restrict third-party or long-lived connections
• Security extensions — May inspect or modify WebSocket traffic

Try:

• Disable extensions for the CrystalQore site
• Test in an incognito/private window (extensions often disabled there)
• Add CrystalQore to your extension's allowlist if supported

7. Refresh the Page

A simple refresh (F5 or Ctrl/Cmd+R) often restores the WebSocket connection:

• Re-establishes the connection
• Clears transient client-side state
• Gets a fresh session if the server rotated tokens

If the issue recurs frequently, investigate network stability or server-side WebSocket configuration.

8. Check for "Reconnecting" or "Disconnected"

If the UI shows connection status:

• Reconnecting — Wait a moment; the client will retry
• Disconnected — Refresh the page or check your network
• Persistent — May indicate a firewall, proxy, or server issue; contact IT or support

---

Self-Hosted / IT Checklist

If you manage the CrystalQore server or network:

---

Quick Checklist

Related Documentation