How to Fix Mirth Connect Java Heap Space Error

Mirth Connect throws java.lang.OutOfMemoryError: Java heap space when the JVM heap is too small for the workload. Fix it by editing mcserver.vmoptions in the Mirth installation directory, setting -Xmx to at least 4096m (4 GB) for production, and restarting Mirth Connect. Never set the heap above 50–60% of system RAM.

This page walks through the 30-second fix, the right way to size the heap, the four cases where the simple fix doesn't work, and the diagnostic sequence that pinpoints which case you have. Written by the engineers who deliver Mirth Connect support for US healthcare organizations.

java.lang.OutOfMemoryError: Java heap space is the JVM telling you it ran out of memory to allocate new objects. The Mirth Connect process needs more heap than it has been given.

The default Mirth Connect installation comes with a 1 GB heap. One gigabyte is fine for development. It is not enough for production. Any production deployment with multiple channels, real message volume, or message attachments will exhaust 1 GB quickly.

For most teams, the entire problem is solved with these five steps:

1. Stop Mirth Connect. On Linux: sudo systemctl stop mirthconnect. On Windows: stop the Mirth Connect Server service.
2. Open mcserver.vmoptions. Located in the Mirth installation directory (/opt/mirthconnect/ on Linux, C:\Program Files\Mirth Connect\ on Windows).
3. Change -Xmx1024m to -Xmx4096m (or higher — see sizing table below).
4. Also set -Xms to match -Xmx. This prevents the JVM from resizing the heap during operation.
5. Restart Mirth Connect. Verify the new heap took effect in the Administrator dashboard.

That fixes the immediate error in most production cases. The rest of this article covers when it doesn't.

Use this table as a starting point. Tune based on your actual workload after measuring.

Hard rule: never set the heap above 50–60% of system RAM. Mirth needs off-heap memory for native code, the operating system needs RAM for page cache, and the JVM itself uses memory beyond -Xmx. Allocating 100% of RAM to heap causes worse problems than the heap error itself.

The default file looks roughly like this:

-Xms256m
-Xmx1024m
-Dsun.net.client.defaultConnectTimeout=10000
-Dsun.net.client.defaultReadTimeout=60000
-Djava.awt.headless=true

After editing for production it should look like this:

-Xms4096m
-Xmx4096m
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200
-Dsun.net.client.defaultConnectTimeout=10000
-Dsun.net.client.defaultReadTimeout=60000
-Djava.awt.headless=true

Setting -Xms equal to -Xmx prevents heap resizing during operation, which gives more predictable memory behavior in production. The G1 garbage collector (-XX:+UseG1GC) generally outperforms the default GC for Mirth's workload profile.

If you've increased the heap and the error still appears, you have one of these four problems.

Problem 1 — Large message attachments held in memory

If your channels handle large attachments (DICOM images, PDF documents, multi-MB HL7 messages), Mirth's default attachment handler keeps them in the heap.

Solution: configure Mirth to store attachments outside the heap. Options:

• Use the File Attachment Handler to write attachments to disk
• Use a Custom Attachment Handler to write to S3 or similar
• Increase channel-level attachment thresholds to keep small messages in-heap but offload large ones

Problem 2 — Memory leak in custom transformer code

JavaScript and Groovy transformers can leak memory if they hold references to large objects in closures, accumulate state in globalMap or channelMap without clearing, or fail to close resources properly.

Solution: profile your transformers under load. Look for:

• Variables stored in globalMap that grow unboundedly
• Database connections or HTTP clients created in transformers without being closed
• Large strings or byte arrays held in closures across messages

For the language-level patterns behind both engines, see Mirth Connect Groovy vs JavaScript transformers.

Problem 3 — Unbounded channel queues

If a destination is slow or unavailable, Mirth queues messages for retry. With no queue size limit, a sustained outage can fill the heap with queued messages.

Solution: configure queue size limits on each channel's destination. Use the channel's Queue Settings to cap the queue and configure error handling for queue-full events.

Problem 4 — Too many concurrent channels for your sizing

Each channel consumes baseline heap. If you've deployed 30+ channels on an undersized JVM, no per-message efficiency will save you.

Solution: either increase heap to match your channel count (table above), or split channels across multiple Mirth nodes.

Run this diagnostic sequence before guessing.

Step 1 — Capture a heap dump on OutOfMemoryError

Add to mcserver.vmoptions:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/log/mirthconnect/heap-dumps/

When the next OOM occurs, you'll have a .hprof file showing what was in memory at the moment of failure.

Step 2 — Analyze the heap dump

Open the .hprof file in Eclipse Memory Analyzer (MAT) or VisualVM. Look at the Dominator Tree to see which objects hold the most memory.

• If the top consumers are message attachment bytes → Problem 1
• If the top consumers are objects from your transformer code → Problem 2
• If the top consumers are queued message objects → Problem 3
• If memory is evenly distributed across channels → Problem 4

Step 3 — Monitor in real time

Add JMX metrics shipping to your monitoring stack (CloudWatch, Datadog, Prometheus). Watch:

• Heap used over time — steady growth = leak, sawtooth = healthy GC
• GC pause time — sustained long pauses = oversized heap or wrong GC algorithm
• Channel queue depths — growing queues = downstream destination problem

A production Mirth Connect deployment should have all of the following in place from day one.

1. Heap sized for actual workload, not defaults. Use the sizing table above.
2. -Xms equal to -Xmx. Predictable memory allocation.
3. G1 garbage collector enabled. -XX:+UseG1GC in mcserver.vmoptions.
4. Heap dump on OOM enabled. So when it does happen, you have data to diagnose.
5. Monitoring on heap usage. Alert at 85% sustained for 5 minutes. By the time heap hits 95%, you have a few minutes before OOM.
6. Attachment offload configured. Don't hold message bodies in heap.
7. Queue size limits configured. Bounded queues prevent runaway memory consumption.
8. Channel partitioning planned. Don't put 50 channels on one undersized node.

For the broader operational picture — thread pools, database tuning, message pruning — see Mirth Connect performance tuning.

Quick answers to the questions that come up most often after teams ship the heap fix.

Will increasing the heap slow down Mirth Connect?

No, larger heaps generally improve performance up to a point. The exception is very large heaps (32 GB+) where GC pauses become longer. For most Mirth deployments, anywhere from 4 GB to 16 GB is the sweet spot.

Should I use the G1 garbage collector or the default?

Use G1. It handles Mirth's typical workload (many short-lived objects from message processing) better than the older parallel collector. Add -XX:+UseG1GC to mcserver.vmoptions.

Why does my Mirth Connect heap usage never drop, even at low traffic?

This is normal up to a point. The JVM holds onto allocated heap rather than returning it to the OS, which is more efficient than constant reallocation. As long as garbage collection is keeping pace and you have headroom under -Xmx, this is expected behavior. If usage is constantly at 95%+ even at low traffic, you have a memory leak.

Can I change the heap size without restarting Mirth Connect?

No. JVM heap settings are set at process startup. A restart is required for any change to -Xmx or -Xms.

How does heap sizing differ on Docker / Kubernetes?

In containerized deployments, use Java 17 (Corretto recommended) and set -Xmx explicitly. Some older JVMs don't correctly detect container memory limits, leading to OOM kills. With Java 17+ and explicit -Xmx set below the container memory limit (leave 25–30% headroom), this is reliable. For full AWS deployment patterns, see Mirth Connect on AWS deployment guide.

What's the relationship between -Xmx and -XX:MaxRAMPercentage?

They're alternatives. -Xmx sets an absolute size (-Xmx4096m = 4 GB). -XX:MaxRAMPercentage=50.0 sets a percentage of available RAM. In containerized environments where memory limits vary, -XX:MaxRAMPercentage can be cleaner. In fixed-VM environments, -Xmx is more predictable.

If you've been through this article and the error persists, the underlying cause is probably:

• A memory leak in transformer code that's not obvious from heap dumps
• A misconfigured attachment handler causing unexpected in-heap retention
• A throughput pattern that exceeds what any reasonable heap size can sustain (architectural rather than configuration problem)

Our free Mirth Connect health check explicitly covers JVM heap sizing, GC tuning, and memory profiling as part of the diagnostic. If your team has been chasing this error for more than a day, a 30-minute screen-share usually pinpoints the cause.

Book a Free Health Check →

For broader Mirth Connect operational guidance, see our Mirth Connect performance tuning guide and our Mirth Connect on AWS deployment guide.

Prefer email? info@tactionsoft.com — we reply within 4 business hours.