Skip to content
Synura Docs

Troubleshooting

Common problems connecting Mirth to Synura and how to fix them.

For any issue, start by running the diagnostic bundle. It collects what Synura support needs if you need to escalate.

Linux / macOS:

Terminal window
./scripts/diagnostic-bundle.sh

Windows (PowerShell):

Terminal window
.\scripts\diagnostic-bundle.ps1

Connection Refused on localhost:2575

Section titled “Connection Refused on localhost:2575”

Symptom: Mirth shows an ERROR status with a “Connection refused” message when sending to localhost:2575.

Cause: stunnel is not running, or it is not configured to listen on port 2575.

Fix:

  1. Check if stunnel is running:

    Terminal window
    # Linux
    systemctl status stunnel
    # or
    ps aux | grep stunnel
    

    # Windows (PowerShell)
    Get-Service stunnel

  2. If stunnel is stopped, start it:

    Terminal window
    # Linux
    sudo systemctl start stunnel
    

    # Windows (PowerShell)
    Start-Service stunnel

  3. If stunnel is not installed, run the setup script again. See Connection Guide, Path B.

  4. Verify the listener is active:

    Terminal window
    netstat -tlnp | grep 2575

Next: test-network to confirm the underlying connection to Synura is reachable once stunnel is running.

TLS Handshake Failed

Section titled “TLS Handshake Failed”

Symptom: TLS or SSL handshake error. In stunnel logs: SSL_connect failed. With a commercial TLS plugin: SSLHandshakeException.

Cause: One of:

  • Java truststore missing the required CA certificates.
  • TLS 1.2 not enabled (older Java versions default to TLS 1.0/1.1).
  • SNI not sent correctly (common with enterprise proxies).

Fix:

  1. Run the diagnostic bundle to capture TLS negotiation details:

    Terminal window
    ./scripts/diagnostic-bundle.sh

  2. Check the Java version on the Mirth server. Synura requires TLS 1.2 as a minimum. Java 8u161+ supports TLS 1.2 by default. Earlier versions may need JVM flags:

    -Dhttps.protocols=TLSv1.2

  3. If using stunnel, check the stunnel configuration file to confirm TLSv1.2 is specified.

  4. If using a commercial TLS plugin (SSL Manager or Zen SSL), ensure the CA certificate is in the Java truststore. Run the keytool import script:

    Terminal window
    # Linux
    ./scripts/keytool-import-linux.sh
    

    # Windows
    scripts\keytool-import-windows.bat

  5. If using an enterprise proxy, confirm with your IT team that SNI is set to {subdomain}.synura.io. Without SNI, Synura will reject the TLS connection.

Next: diagnostic-bundle to capture the full TLS handshake output for Synura support.

Connection Timeout

Section titled “Connection Timeout”

Symptom: Connection hangs and eventually times out. The test-network script also times out.

Cause: A firewall or network policy is blocking outbound TCP 443 to synura.io.

Fix:

  1. Run the network test script to confirm:

    Terminal window
    ./scripts/test-network.sh {subdomain}.synura.io

  2. If the test times out, the issue is between your Mirth server and the internet. Common blockers:

    • Corporate firewall blocking outbound 443.
    • HTTP proxy intercepting HTTPS (MLLPS is not HTTP and cannot pass through a standard HTTP proxy).
    • Network segmentation placing the Mirth server in a restricted VLAN.

  3. Ask your network team to allow outbound TCP 443 from the Mirth server to synura.io. The diagnostic bundle output contains IP addresses if they need to allowlist by IP.

  4. If all traffic goes through an HTTP proxy, the MLLPS traffic must be allowed to pass directly or through a TCP-level proxy (SOCKS or transparent TCP proxy).

Next: test-network to confirm connectivity after the firewall change.

Message Sent but No AA Response

Section titled “Message Sent but No AA Response”

Symptom: Message shows as SENT but no ACK is received, or the response times out.

Cause: One of:

  • Response timeout in Mirth is too short for the message size or network latency.
  • Sending facility in MSH-4 does not match what is configured in Synura, so routing fails.

Fix:

  1. Increase the Response Timeout on the TCP Sender destination in Mirth:

    • Open the channel, go to the Destination tab.
    • Increase “Response Timeout (ms)” to 30000 (30 seconds) as a test.
    • Save and redeploy.

  2. Check the MSH-4 (Sending Facility) field in your HL7 message. This value must match the sending facility registered in your Synura configuration. Log into the Synura dashboard and verify under your organisation’s settings.

  3. If the sending facility is correct and the timeout is generous, run the diagnostic bundle and contact Synura support. The issue may be on the routing side.

Next: diagnostic-bundle to capture message and connection details.

InvalidChannel on Import (Mirth 3.8.1)

Section titled “InvalidChannel on Import (Mirth 3.8.1)”

Symptom: Importing a channel XML file fails with InvalidChannel, XStream or a deserialization exception.

Cause: Mirth 3.8.1 has a known XStream bug that breaks channel imports. The channel file is fine. The deserializer is not.

Fix:

  • Do not import channel XML on Mirth 3.8.1. Create the channel manually through the GUI instead.
  • Follow the step-by-step instructions in Mirth Channel Setup. The manual setup takes only a few minutes.

If you are on Mirth 3.9+ or 4.x, channel import works correctly and you can use it if preferred.

stunnel Will Not Install

Section titled “stunnel Will Not Install”

Symptom: Setup script fails due to insufficient permissions, or the package manager cannot install stunnel.

Cause: stunnel requires administrator (root/sudo) access. Locked-down servers may not allow this.

Fix:

  1. If you have access to an admin account, run the script with elevated privileges:

    Terminal window
    sudo ./scripts/keytool-import-linux.sh

  2. If you cannot get admin access, use Path C: Enterprise TLS Proxy instead. Your infrastructure team can configure an existing TLS proxy (F5, HAProxy, nginx, etc.) to forward traffic to Synura. See Connection Guide, Path C, for the configuration details to provide to your IT team.

  3. If neither option is available, contact Synura support. We can discuss alternative approaches for your environment.

javaws Not Found / Mirth Administrator Does Not Launch

Section titled “javaws Not Found / Mirth Administrator Does Not Launch”

Symptom: The Mirth Administrator launcher does nothing, or you see an error about javaws not being found.

Cause: Mirth 3.x uses Java Web Start (javaws), which is only included in Oracle JDK 8. OpenJDK does not include it.

Fix:

  1. Install Oracle JDK 8 (specifically, a version that includes javaws). This is separate from whatever Java runtime Mirth Connect itself uses.

  2. Ensure javaws is on your system PATH:

    Terminal window
    which javaws
    # Should return a path, e.g. /usr/bin/javaws

  3. On Windows, the Oracle JDK 8 installer typically registers .jnlp files to open with Java Web Start automatically. If not, right-click the .jnlp file, select “Open with”, and browse to javaws.exe in your JDK installation directory (e.g. C:\Program Files\Java\jdk1.8.0_xxx\bin\javaws.exe).

  4. If you cannot install Oracle JDK 8, use the Mirth Connect Administrator Launcher desktop application if your Mirth version shipped with one (Mirth 3.9+ includes a standalone launcher).

  5. For Mirth 4.x, the Administrator is a standalone application and does not require Java Web Start.

Contact Support

Section titled “Contact Support”

If your issue is not listed here, run the diagnostic bundle and contact support@synura.io with your subdomain, Mirth version and the bundle output.