Mirth Connect
Issues & Fixes
Comprehensive troubleshooting guide for common Mirth Connect problems — channel failures, MLLP errors, transformer exceptions, memory issues, and FHIR connector problems. Plus expert support when you need it.
Report a Mirth Connect Issue
Describe your issue and our engineers will respond within 2 hours for critical problems.
Common Mirth Connect Problems
and How to Fix Them
Our Mirth Connect engineers have resolved thousands of channel failures, integration errors, and performance issues. Here are the most common problems and proven fixes.
Channel Won't Start / Stays in Error State
A Mirth Connect channel fails to start or immediately transitions to an Error state after deployment.
!Common Causes
- Invalid transformer JavaScript syntax
- Misconfigured source or destination connector settings
- Port conflicts with another application or Mirth channel
- Missing or incorrect SSL/TLS certificate configuration
✓Recommended Fixes
- Review the channel error log in the Mirth Connect Administrator dashboard
- Validate JavaScript transformer code using the code template editor
- Check that the listener port is not in use by another process (netstat -an)
- Ensure SSL certificates are imported into the Mirth Connect keystore correctly
MLLP Connection Timeouts & Dropped Messages
HL7 messages sent via MLLP are timing out, not being received, or causing connection resets between systems.
!Common Causes
- Firewall rules blocking MLLP port (typically 6661)
- Incorrect MLLP framing characters on sender or receiver
- Network latency exceeding Mirth's default socket timeout
- Source system not sending ACK within expected timeframe
✓Recommended Fixes
- Verify firewall rules allow TCP traffic on the configured MLLP port
- Confirm MLLP start block (0x0B) and end block (0x1C 0x0D) characters match between systems
- Increase socket timeout in channel connector settings (Connection Timeout field)
- Enable 'Send ACK' option on the source connector and verify acknowledgment mode is set correctly
JavaScript Transformer Errors
Channel transformer throws exceptions, causing messages to be queued in the error state or routing incorrectly.
!Common Causes
- NullPointerException when accessing missing HL7 fields
- Incorrect segment or field indexing (HL7 is 1-based in Mirth)
- Undefined variable references in multi-step transformation logic
- Wrong message format passed to a transformer expecting a specific HL7 type
✓Recommended Fixes
- Use defensive checks: if (msg['PID']['PID.3']['PID.3.1'].toString() != '') before accessing fields
- Review Mirth's HL7 field indexing — PID.3.1 is the first component of the 3rd PID field
- Use the Mirth Connect message log to inspect the raw message before transformation
- Add try/catch blocks around critical transformer logic to capture and log errors gracefully
High Memory Usage / OutOfMemoryError
Mirth Connect server consuming excessive memory, leading to OutOfMemoryError exceptions or server crashes.
!Common Causes
- Large message attachments stored in memory during processing
- Too many channels running simultaneously without resource limits
- Message queue backlog growing due to slow destination systems
- Insufficient JVM heap size for the volume of messages processed
✓Recommended Fixes
- Increase JVM heap size in the mirth.properties file (set -Xms and -Xmx values)
- Enable message pruning to prevent unbounded growth of stored message history
- Configure channel queuing limits and message storage settings
- Upgrade to a dedicated server with more RAM for high-volume environments
Database Connection Pool Exhaustion
Mirth Connect unable to obtain database connections, causing channel errors and message delivery failures.
!Common Causes
- Too many channels making concurrent database queries
- Database connection pool size too small for workload
- Connections not being released after queries complete (connection leak)
- External database server unavailable or overloaded
✓Recommended Fixes
- Increase the database connection pool size in mirth.properties (database.max-connections)
- Review channel JavaScript for database connections not explicitly closed after use
- Monitor database server health and query performance
- Consider migrating to a dedicated external database (PostgreSQL or MySQL) if using embedded Derby
FHIR Connector Authentication Failures
Mirth Connect's FHIR listener or HTTP sender returning 401 Unauthorized or 403 Forbidden errors when exchanging FHIR resources.
!Common Causes
- Expired OAuth 2.0 access token not being refreshed automatically
- Incorrect client credentials in the HTTP sender connector
- SMART on FHIR scope mismatch — requested scopes not granted by the authorization server
- IP whitelist restrictions on the FHIR server blocking Mirth's outbound IP
✓Recommended Fixes
- Configure token refresh logic in the Mirth channel using the HTTP sender's pre-processing script
- Verify client_id, client_secret, and token endpoint URL in connector settings
- Review SMART app registration to ensure required scopes (patient/*.read, etc.) are enabled
- Confirm Mirth's outbound IP is whitelisted on the target FHIR server
Still Stuck? Our Mirth Connect
Engineers Are Ready to Help
Sometimes issues require hands-on expert investigation. Our Mirth Connect support team provides rapid diagnosis and resolution for even the most complex integration problems.
Emergency Channel Recovery
Critical channel down? Our team provides rapid response to diagnose and restore failed Mirth Connect channels, minimizing disruption to clinical workflows.
Root Cause Analysis
We investigate recurring channel failures, message loss events, and performance degradation — identifying the root cause and implementing permanent fixes.
Performance Optimization
Tune Mirth Connect's JVM settings, channel threading, database connection pools, and message storage to maximize throughput and minimize latency.
Version Upgrades
We manage Mirth Connect version upgrades and migrations — including channel compatibility reviews, rollback planning, and production cutover coordination.
Monitoring Setup
Implement proactive monitoring for channel status, message volumes, error rates, and system health — with alerting configured to notify your team before problems escalate.
Managed Support Plans
Ongoing managed support with defined SLAs — covering 24/7 channel monitoring, incident response, change management, and quarterly performance reviews.
Mirth Connect Down? We Can Help.
Don't let a channel failure disrupt patient care. Our Mirth Connect engineers provide rapid diagnosis and resolution — available for emergency engagements and ongoing managed support.
- 2-hour response for critical issues
- US-based Mirth Connect engineers
- Remote access support available
- Managed support plans with defined SLAs
Get Mirth Connect Support Now
Describe your issue and our engineers will be in touch within 2 hours for critical problems.