Troubleshooting connections
Use this guide when a connection is Active but the tunnel isn’t working, or when a connection is stuck in an unexpected state.
Step 1: Check activation status vs. connectivity
Section titled “Step 1: Check activation status vs. connectivity”These are two different things. Go to the Connections page and look at both:
- Activation status (Ready, Active, Paused, Failed, etc.) — what you’ve configured.
- Connectivity indicator (Connected, Disconnected, Never connected) — whether the gateway is live right now.
A connection that is Active but shows “Never connected” means the gateway plugin has never successfully connected — not a temporary blip. “Disconnected” means it has worked before but isn’t currently live.
See Connection statuses for the full reference.
Step 2: Check for an unaccepted offer (Admin connections)
Section titled “Step 2: Check for an unaccepted offer (Admin connections)”If the connection is in Offered state, the peer has not accepted it yet. The peer needs to go to their Connections page, find the offer, and click Accept. Until they do, no tunnel is possible.
Step 3: Verify the Connection ID and Shared Secret
Section titled “Step 3: Verify the Connection ID and Shared Secret”Open the connection detail and check the Connection ID. Then open your Mirth server’s Gateway Connector plugin settings and confirm:
-
The Connection ID in the plugin matches the one on this page exactly.
-
The Shared Secret was entered correctly. How you recover it depends on the connection type:
- Admin connections: use View Secret on the connection detail to reveal it again (rate-limited), then re-enter it in the plugin.
- P2P connections: the secret is shown only once per owner and is deleted once both sides have viewed it. If it’s already been viewed, View Secret reports that the secret is no longer available. Use Rotate Secrets on the connection detail to generate a new secret, then re-enter that value in the plugin.
A mismatch in either value causes the gateway to fail authentication silently.
Step 4: Confirm the peer is enabled
Section titled “Step 4: Confirm the peer is enabled”For P2P connections, open the Authorized Peers table in the Mirth Gateway Listener connector settings and confirm the peer is enabled. Each peer has an individual enable/disable toggle — a disabled peer cannot connect even if the connection is Active.
Step 5: Check network and TURN access
Section titled “Step 5: Check network and TURN access”The gateway uses WebRTC NAT traversal by default, which requires:
- Outbound access to the MQTT signaling broker (
wss://dev-mqtt.mdds-llm.com/mqtt). - Outbound access to the TURN server (
dev-turn.mdds-llm.com, port 443 TCP/UDP).
If your network blocks outbound connections on non-standard ports or to specific hostnames, the ICE negotiation will fail and the tunnel won’t open. Contact your network team to confirm these are reachable from the Mirth server.
Step 6: Check for a Failed status
Section titled “Step 6: Check for a Failed status”If the connection shows Failed, open the detail view and read the error message. You can retry by clicking Retry (which moves the connection back to Ready), then Activate it again.
Pausing and resuming
Section titled “Pausing and resuming”If you need to take a connection offline temporarily without terminating it, click Pause. This suspends the connection in the platform. To bring it back, click Resume (which re-activates it). Pausing does not forcibly disconnect active tunnels on the Mirth side — it prevents new ones from being established.
Still stuck?
Section titled “Still stuck?”If none of the above resolves the issue, gather the connection ID and status details and see Getting support.