Gateway connectivity problems

Most gateway connectivity problems fall into a small number of categories. Start with the connection status shown in the Contact System UI, then work through the checks below.

Reading connection status

The Connections page shows a separate activation status and real-time connectivity indicator for each connection — see statuses for the full list. When diagnosing connectivity, the real-time indicators are what you watch:

Indicator	Meaning
Connected	The gateway is currently online for this connection and the tunnel is established. Traffic can flow.
Disconnected	The gateway was connected before but is not right now. The tunnel has dropped.
Never connected	The connection has been provisioned and is Active, but the gateway has never come online for it. Usually means the plugin has not started or the secret could not be fetched.

“Never connected” on an Active connection is the most actionable signal — it means the connection was never established, not that it dropped.

Common causes

Firewall blocking outbound MQTT or STUN/TURN

WebRTC mode requires outbound TCP/UDP access to the MQTT signaling broker (port 443 by default) and to STUN/TURN servers. If a firewall blocks these:

• The gateway will fail to signal and tunnels will not establish.
• Check that dev-mqtt.mdds-llm.com:443 (MQTT over WebSocket/TLS) is reachable from the Mirth server.
• Check that the TURN server (dev-turn.mdds-llm.com:443) is reachable for both TCP and UDP.

Tip

TURN port 443 is used specifically for firewall compatibility — most enterprise firewalls allow outbound 443. If tunnels still fail, check whether the firewall does deep-packet inspection that blocks non-HTTPS traffic on port 443.

TURN unreachable

If STUN succeeds (direct NAT traversal) but TURN relay fails, connections will work on simple NAT but fail through symmetric NAT or restrictive corporate firewalls. Signs:

• Connection works from one site but not another.
• The gateway logs show it cannot find a working network path (no relay candidates) and the connection attempt stalls.

Verify the TURN server is up and that credentials are valid. TURN credentials are time-limited and auto-generated — if the plugin has been running without restart for an extended period, restart Mirth to refresh them.

Authentication secret problems

Each peer tunnel is authenticated with a per-connection secret. For Gateway Listener and Sender channel connectors, you never enter this secret yourself — there is no secret field in the connector. The connector fetches the secret automatically when the channel starts, using the server’s own credentials, and holds it only in memory.

Because there is nothing to paste, a secret problem on a channel connector shows up as the tunnel failing to start after a redeploy, not a typo. This usually means the secret could no longer be fetched — the connection grant was revoked, or the server is no longer registered in the Contact System.

If a channel connector tunnel will not start:

1. Re-deploy the channel so the connector fetches a fresh secret.
2. In the Contact System, confirm the connection is still Active and the grant has not been revoked.
3. Confirm the server is still registered.

Note

The “paste a token” workflow applies only to the separate Admin Tunnel feature, where you paste a one-time server registration token and save. That token registers a server — it is not the per-connection secret used by Gateway channel connectors.

Peer not approved or paused in the cloud dashboard

A Gateway Listener accepts the peers approved for it in the Contact System — there is no per-peer list to manage on the Mirth server itself. If a peer cannot deliver messages even though its connection looks Active, check the Connections page: a connection that has been paused or revoked there will stop that peer’s tunnel without affecting the others.

Plugin not running or not deployed

If the Gateway Connector plugin is not installed, not deployed, or failed to start:

• Channels using Gateway Listener or Sender connectors will fail to deploy.
• The gateway will not subscribe to MQTT, so all connections will show as Never connected.

Check the Mirth server logs for gateway plugin startup errors.

Advanced

If the plugin fails to start, the logs usually point to one of a few server-environment causes: the operating system preventing the plugin from loading its bundled native networking libraries (common when the system temp directory is mounted with noexec), missing gateway runtime libraries, or a Java networking-library initialization error. These are deployment-environment issues for whoever installs the plugin, not settings you change in the Contact System.

WebRTC vs. Direct mTLS

Situation	Recommended mode
Standard deployment, NAT/firewall between sites	WebRTC / NAT traversal (default)
Both servers have stable, routable IPs and a direct network path	Direct mTLS
WebRTC tunnels establish but drop frequently	Try Direct mTLS if a direct path exists
Environment with deep-packet inspection that breaks DTLS	Direct mTLS

Direct mTLS is simpler to debug (it is a standard TLS TCP connection) but requires that both servers be reachable at fixed addresses. WebRTC handles NAT automatically but adds signaling and ICE negotiation steps that can be affected by network policy.

Note

Switching connection modes requires updating both sides — the listener and the sender — and reprovisioning the connection. Coordinate the change with your peer organization.