Fixing “Unable to Connect to the UCP Node Server” and “xhr poll error” in FreePBX

Overview

In FreePBX, the UCP Node Server powers real-time features in the User Control Panel (UCP) using WebSocket connections.When these connections fail, you may see errors such as:

• Unable to connect to the UCP Node Server. Error: xhr poll error

• Unable to authenticate with the UCP Node Server

• Browser console errors like:

  net::ERR_CERT_AUTHORITY_INVALID

• 
  

These errors occur because the UCP Node Server is separate from Apache and may not share the same SSL/TLS certificate configuration.If UCP Node is using a self-signed or mismatched certificate, modern browsers will block the WebSocket connection.

Why It Happens

1. Different SSL CertificatesApache may have a trusted certificate for the FreePBX GUI (e.g., Let’s Encrypt), but UCP Node defaults to its own self-signed cert.

2. HTTPS & Mixed ContentIf the GUI is accessed over HTTPS, browsers require UCP Node to also use HTTPS (wss://).If UCP Node is running plain HTTP (ws://) on port 8001, the browser will block it.

3. Port or Binding IssuesUCP Node may be bound to localhost (127.0.0.1) or IPv6 only, preventing remote browsers from connecting.

4. 
   

How to Fix It

Step 1 — Confirm UCP Node Is Reachable

From your browser:

https://pbx.examplecompany.com:8003/socket.io/?EIO=3&transport=polling

If you get output like:

97:0{"sid":"abc123","upgrades":["websocket"],"pingInterval":25000,"pingTimeout":20000}

…the network connection is working.

If not, ensure port 8003/TCP is open and UCP Node is bound to 0.0.0.0:

fwconsole setting NODEJSBINDADDRESS 0.0.0.0
fwconsole setting NODEJSHTTPSBINDADDRESS 0.0.0.0
fwconsole reload
fwconsole restart ucp

Step 2 — Enable SSL for UCP Node and Use a Trusted Certificate

Identify the certificate files in /etc/asterisk/keys/:

/etc/asterisk/keys/pbx.examplecompany.com.crt
/etc/asterisk/keys/pbx.examplecompany.com.key
/etc/asterisk/keys/pbx.examplecompany.com-fullchain.crt

Apply them to UCP Node:

fwconsole setting NODEJSTLSENABLED true
fwconsole setting NODEJSHTTPSBINDPORT 8003
fwconsole setting NODEJSTLSPRIVATEKEY /etc/asterisk/keys/pbx.examplecompany.com.key
fwconsole setting NODEJSTLSCERTFILE /etc/asterisk/keys/pbx.examplecompany.com.crt
fwconsole setting NODEJSTLSCABUNDLEFILE /etc/asterisk/keys/pbx.examplecompany.com-fullchain.crt
fwconsole restart ucp

Step 3 — Test the Certificate

In your browser:

https://pbx.examplecompany.com:8003/socket.io/?EIO=3&transport=polling

You should now see no certificate warning and receive the polling handshake data.

Step 4 — Reload UCP

Log back into the FreePBX GUI and open UCP.The xhr poll error and Unable to authenticate messages should be gone.

Summary

These UCP errors are almost always caused by SSL certificate mismatches or browser security policies blocking untrusted WebSocket connections.The fix is to:

1. Ensure UCP Node is reachable on its port (8001 or 8003).

2. Bind it to the correct interface (0.0.0.0).

3. Enable SSL and configure it with the same trusted certificate used by Apache.

With these changes, UCP’s real-time features will work reliably without browser warnings.