Skip to content

Connection issues

This page is for IT providers whose practice has Halo Link installed but not connecting to Halo Connect. It lists what Halo Link needs from the server and network, and where it most often gets blocked.

Symptoms

The latest application log repeats lines like these:

[10:42:17 ERR HaloLink] Failed to initialise session. Failed to open session at pmssessions. StatusCode: 0. Body: n/a.
[10:42:17 INF HaloLink] Setting retry for Session init in 600 seconds.

StatusCode: 0 means Halo Link got no response at all. The connection was stopped before it reached Halo Connect, so the cause is almost always on the practice's network or server.

Halo Link only makes outbound HTTPS connections on TCP port 443. It needs no inbound ports.

Host Used for
api.haloconnect.io The Halo Connect API. Halo Link can't start a session without it.
wps-haloapi-prod.webpubsub.azure.com Receiving queries in real time (WebSocket over 443).
*.blob.core.windows.net Uploading query results.
downloads.haloconnect.io Halo Link updates.

These are the production hosts. The staging hosts are listed on the Enterprise deployment page.

Checks

Test the connection

Send a request from the server to https://api.haloconnect.io/link/pmssessions.

  1. Preliminary check: browse to the URL from the server. This runs as your own account with your proxy settings, so it can pass even when Halo Link is blocked.
  2. Confirming check: send the same request as the account the service runs as (Local System by default), so it uses that account's proxy settings. For example, run Invoke-WebRequest from a scheduled task or PowerShell session running as SYSTEM. PowerShell shows Halo Connect's error response as an error, which still counts as a pass.

The confirming check decides the result:

  • Pass: any error response from Halo Connect, such as "Resource not found" or "Unauthorized". The request has no Halo Link credentials, so it's expected to be refused.
  • Fail: no response, a timeout, a certificate warning, a block page from a firewall or filter, or a proxy login prompt.

If this test fails, the sections below help narrow down why.

Service

Halo Link runs as the Windows service Halo Link Service, under the Local System account.

  • The service should be running and set to start automatically.
  • If it has been changed to run as another account, that account needs the same network access.

DNS

  • api.haloconnect.io should resolve to a public IP address.
  • No local DNS record, override or DNS filtering service should redirect or block haloconnect.io.

Firewall and filtering

  • Outbound TCP 443 should be allowed from the server to every host in the table above.
  • Check host-based firewalls on the server as well as the network firewall.
  • Web filtering, intrusion prevention, application control and geo-blocking can all block or reset these connections. All the hosts are in Microsoft Azure.

HTTPS inspection

A very common cause

Firewalls that perform SSL/TLS inspection (also called HTTPS scanning or deep packet inspection) replace the Halo Connect certificate with their own. Halo Link checks the certificate it receives, and refuses the connection.

  • The certificate the server receives for api.haloconnect.io should be issued by a public certificate authority, not by a firewall or security product.
  • Exclude the hosts in the table above from SSL/TLS inspection.

Proxy

Skip this section if the practice doesn't use a proxy.

Halo Link has no proxy setting of its own. See Proxy server configuration for the ways to set one.

  • The proxy setting must apply to the Local System account, not only to logged-in users.
  • Local System can't sign in to a proxy. Either let the hosts above through without authentication, or bypass the proxy for them.

TLS, .NET and Windows updates

  • TLS 1.2 or later must be enabled for outbound connections. Halo Connect doesn't accept older versions, and Halo Link uses the Windows defaults.
  • .NET Framework 4.8 or later must be installed.
  • Windows updates, including root certificate updates, should be current.

Clock

The server's date, time and time zone must be correct, because a wrong clock breaks certificate checks. See System requirements for how to resync it.

Confirming the fix

Halo Link waits longer between each retry, up to 10 minutes, so restart the service after making a change. Then check the newest log file. A successful connection logs lines like these, and the Failed to initialise session error stops:

[10:51:03 INF HaloLink] Session 27bf71c0-52fa-47ec-b561-dedec93d8757 opened.
[10:51:03 INF HaloLink]   WebPubSub BaseUrl = wss://wps-haloapi-prod.webpubsub.azure.com/client/hubs/HaloConnect

Still not connecting?

Contact Support and include:

  • which of the checks above pass and which fail
  • the latest Halo Link log file
  • the make and model of the practice's firewall or router, and whether it does HTTPS inspection or web filtering
  • the practice's public IP address, so we can check whether its traffic reaches us
Version: 26.1019.11407