Where do I find the exact reason Mirth won't start?

Check wrapper.log on the server itself, since the Administrator client can't show any useful detail when it can't connect to a server that never finished starting. The last several lines before the process exits almost always name the specific failure.

Does a port conflict always throw an obvious error?

Usually yes — an address-in-use message is one of the clearer startup failures Mirth produces, naming the port directly. It's still worth confirming which process actually holds that port before assuming it's safe to reassign Mirth's own configuration to a different one.

Can I recover if the Derby database is corrupted?

Sometimes, using Derby's own repair utilities, but a clean restore from a recent backup is far more reliable and faster than attempting to salvage a corrupted file. This is the main reason routine backups matter even for an embedded database.

Is switching from Derby to an external database worth it?

For production environments with meaningful message volume, many teams do move to an external database for better backup tooling and easier recovery, though it adds its own operational overhead that a smaller instance may not need to take on yet.

What's the minimum memory Mirth needs to start?

This varies by version and channel complexity, so check your specific release's documentation rather than assuming a fixed number applies universally, and always leave headroom above the bare minimum for normal operation once channels are actually running in production under real load.

Does an expired license stop the server from starting?

On commercial installations, yes — Mirth checks license validity as part of startup, and an expired or missing license file will prevent the server from completing that process entirely, regardless of how correctly every other setting is configured otherwise on that server.

Mirth Connect Server Won't Start: Cause and the Fix

TL;DR

A Mirth Connect server that won't start almost always fails one of four startup checks in order: port availability, its internal Derby database, JVM memory allocation, or license validation. Read wrapper.log first — the Administrator client can't show anything useful since it can't connect to a server that never came up. Fix it by freeing or reassigning the conflicting port, restoring Derby from backup, adjusting memory flags in wrapper.conf to match the host, or reinstalling a valid license file. Prevent recurrence with reserved ports, scheduled database backups, and pre-upgrade memory checks.

Quick answer

A Mirth Connect server won't start situation shows almost no useful detail in the Administrator client, since the client can't connect to a server that never came up — the real information lives in wrapper.log. Common entries there include "Address already in use" for a port conflict or a Derby database startup failure for a corrupted internal store.

Below is how to read that log correctly, the fix for each common cause, and how to prevent the same failure next time. Our free Mirth Health Check can trace the exact startup failure for you — part of the Mirth Connect support work we do for US healthcare teams.

What Causes the Mirth Connect Server Not to Start?

Mirth's startup sequence checks several things in order — port availability, its internal database, memory allocation, and licensing — and a failure at any one of these stops the whole server before the Administrator interface becomes reachable at all. Reading wrapper.log in sequence, rather than jumping straight to the last line, usually shows exactly which specific check failed first, and why it did, without needing to guess across the whole startup process.

Port Already in Use by Another Process

If another application has already claimed the port Mirth's web interface or API is configured to use, the server fails immediately with an address-in-use error. This is common after another service was installed on the same host.

Corrupted Internal Derby Database

Mirth's default embedded Derby database can become corrupted after an unclean shutdown, a disk-full event, or a forced process kill during a write. The server log shows a database startup failure rather than any message-processing error.

Insufficient Memory Allocated at Startup

If the JVM's configured heap or Metaspace settings in wrapper.conf exceed what the host actually has available, the server fails to start rather than starting and crashing later. This often surfaces right after a server is resized.

Missing or Invalid License File

Commercial Mirth installations require a valid license file in the expected location, and a missing, expired, or corrupted license will prevent the server from completing startup, independent of any other configuration being correct.

How to Fix a Server That Won't Start

Open wrapper.logimmediately and read the last entries before the process exits, since the exact failure reason is almost always written there even when the Administrator client shows nothing useful at all. The four fixes below correspond directly to the four causes above, so match the log's exact wording before applying one, rather than working through all four blindly and hoping one of them resolves the actual startup problem.

Free the Conflicting Port or Reassign Mirth's Port

Identify whatever process is holding the conflicting port using your operating system's own tools, and either stop that process or change Mirth's configured port in its properties file. Restart the service once the port is available.

Restore the Derby Database From Backup

If the internal database is corrupted beyond repair, restore it from your most recent backup rather than attempting to salvage a damaged file. This is exactly why regular Derby backups matter even for a database many treat as disposable.

Increase Startup Memory in wrapper.conf

Adjust the JVM memory flags in wrapper.conf to match what the host can actually provide, rather than leaving settings sized for a previous, larger server. Confirm available memory on the host directly before setting a new value.

Reinstall or Renew the License File

Place a current, valid license file in the location Mirth expects it, matching the format and naming convention for your installed version. Restart the service afterward to confirm the license is now recognized correctly.

How to Prevent Startup Failures in Production

A server that won't start is almost always entirely preventable, since ports, database health, memory sizing, and licensing are all things you can check proactively rather than discover during an actual outage. The habits below take little ongoing effort and remove nearly every cause of a surprise startup failure in production, well before it becomes a real incident that costs you downtime and a late-night fix under pressure.

Reserve Dedicated Ports for Mirth Services

Document and reserve the specific ports Mirth uses on each host, and avoid installing other services that might claim the same range without checking first. This single habit prevents the most common startup failure entirely.

Schedule Regular Database Backups

Back up Mirth's internal database on a defined schedule, whether it's the default Derby store or an external database, so a corruption event costs you a restore rather than a rebuild from nothing.

Monitor Disk and Memory Before Upgrades

Before resizing a host or moving Mirth to new infrastructure, confirm the memory and disk settings in wrapper.conf actually match the new environment rather than carrying over settings from the old one unchanged.

Track License Expiration in Advance

Keep the license renewal date visible somewhere your team actually checks, well ahead of expiration, so a routine restart or upgrade doesn't unexpectedly surface a licensing failure you weren't tracking.

When to call for help

If wrapper.log doesn't clearly point to one of these four causes, the failure may be an interaction between them — a memory setting that looks fine alone but conflicts with a Derby recovery attempt, for example. Our free Mirth Connect health check traces the exact startup failure as part of the standard diagnostic.

Book a Free Health Check →

Have the wrapper.log output ready? Send us the log, or check pricing for ongoing support plans.

Mirth Connect Server Won't Start: Causes and Fix