Troubleshooting Agent Connection Issues

This guide helps diagnose and resolve issues where the Polar Cloud Agent loses its WebSocket connection due to network or security configuration problems.

---

Basic Sanity Check (Do This First)

Before troubleshooting firewalls, proxies, or WebSocket timeouts, confirm the most basic network assumptions:

• Can you ping any of the printers? If not, the issue is basic network reachability.
• Is the agent device on the same network, LAN, or subnet as the printer? The agent and printers should typically be on the same local network.
• Is the agent on Wi-Fi if the printers are on Wi-Fi? Guest networks, VLANs, and segmented Wi-Fi networks can block device discovery.
• Check the IP address ranges:
  • If your printer IP is 10.x.x.x, the agent must also be on a 10.x.x.x network
  • If your printer IP is 192.168.x.x, the agent must also be on 192.168.x.x
  • If these don’t match, the agent will not be able to find or talk to the printer

---

Quick Summary Checklist (Start Here)

• WebSocket timeout is set to 300–600 seconds (or disabled for Polar Cloud)
• *.polar3d.com is fully whitelisted
• SSL/TLS inspection is disabled for Polar Cloud domains
• Proxy server explicitly supports WebSocket (wss://)
• No firewall or gateway is terminating idle TCP sessions at 60 seconds

---

Quick Summary Checklist (Start Here)

• WebSocket timeout is set to 300–600 seconds (or disabled for Polar Cloud)
• *.polar3d.com is fully whitelisted
• SSL/TLS inspection is disabled for Polar Cloud domains
• Proxy server explicitly supports WebSocket (wss://)
• No firewall or gateway is terminating idle TCP sessions at 60 seconds

---

---

Primary Failure

WebSocket Connection Keeps Dropping

The network is dropping the WebSocket connection every 60 seconds. This prevents the agent from maintaining a stable, persistent connection to Polar Cloud.

What This Usually Means

Your firewall, proxy, or network hardware is closing idle sessions too aggressively. WebSocket connections must stay open continuously.

---

1. WebSocket Connection Timeout

Your firewall or network equipment is likely configured to close idle connections after 60 seconds. This must be increased to support persistent WebSocket traffic.

Where to Check

• Firewall settings: TCP timeout, idle timeout, or session timeout
• Proxy server settings: WebSocket timeout or keep-alive
• Router/Gateway: Connection tracking timeout

Specific Settings to Change

• Set WebSocket idle timeout to 300–600 seconds (5–10 minutes)
• Or disable timeout entirely for connections to:
  • *.polar3d.com
  • Your specific Polar Cloud server domain

---

2. Whitelist Polar Cloud WebSocket Traffic

Add these domains to your firewall or proxy allowlist with no timeout or persistent connection rules.

Domains to Whitelist

• *.polar3d.com
• Any specific Polar Cloud server domains your organization uses
• Ensure the WebSocket protocol (wss://) is explicitly allowed

Firewall Rule Example

• Source: Any
• Destination: *.polar3d.com
• Protocol: HTTPS/WSS (port 443)
• Action: Allow
• Session Timeout: Disabled or 600+ seconds

---

3. Disable SSL/TLS Inspection for Polar Cloud

If your network uses SSL inspection or deep packet inspection, it may interfere with WebSocket connections.

What to Do

• Add Polar Cloud domains to the SSL/TLS inspection bypass list

Why This Matters

SSL inspection often breaks the persistent connection handshake required by WebSockets.

---

4. Check for Proxy Server Interference

If your network uses a proxy server (such as Squid, Blue Coat, Zscaler, etc.), it must be explicitly configured to support WebSockets.

Required Proxy Settings

• Enable full WebSocket support
• Disable connection pooling for WebSocket connections
• Increase proxy timeout to 600+ seconds
• Add Polar Cloud domains to the proxy bypass list (if supported)

---

5. Network Equipment to Check

Review configuration on the following systems:

• Firewall appliances
• Internet gateway or edge router
• Content filters
• Cloud-based security gateways
• Internal proxy servers

---

6. Running on a Server?

If you are running the Polar Cloud Agent on a Windows or Linux server (instead of a personal computer), additional networking differences may apply.

Run the following tests directly from the server command line to verify WebSocket connectivity:

Test Basic HTTPS Connectivity

curl -I https://printer4.polar3d.com

Test WebSocket Upgrade (If wscat Is Available)

wscat -c wss://printer4.polar3d.com/socket.io/?transport=websocket

Other Quick Server Checks

# Check DNS resolution
nslookup printer4.polar3d.com

# Check if port 443 is reachable (Windows PowerShell)
Test-NetConnection -ComputerName printer4.polar3d.com -Port 443

# Check system time (Windows)
w32tm /query /status

If WebSocket Connections Are Still Blocked on the Server

These are the most common server-specific causes:

• SSL certificate issue: The server may lack a trusted root CA or full certificate chain
• DNS issue: printer4.polar3d.com may resolve differently on your network
• IPv6 vs IPv4 mismatch: IPv6 may resolve but only IPv4 is properly routed
• Proxy settings: Windows or system-level proxy may interfere even if the firewall allows traffic
• Incorrect system time: SSL certificates fail validation when server time is incorrect

---

7. Testing Steps

Use these steps to confirm whether the issue is network-related and help your IT team isolate the cause:

Step 1: Test From a Different Network

• Try a home network or mobile hotspot
• If it works there, it confirms the issue is with your school or corporate network

Step 2: Temporarily Disable Firewall or Proxy (If Allowed)

• If the connection becomes stable, the firewall or proxy is confirmed as the cause

Step 3: Check IT Logs

• Look for repeated connection drops at or near 60-second intervals
• Check for WebSocket denials, resets, or timeout errors

Step 4: Work With IT to Implement Whitelisting

• Provide your IT team with the Polar Cloud domain list
• Request WebSocket timeout increases to 600 seconds
• Confirm SSL inspection bypass is in place