Troubleshooting healthcare interfaces
Every symptom a clinical interface shows, mapped to its cause and the page with the fix.
A clinical message passes through layers - the network, MLLP framing, routing, parsing, your service, its destinations - and a failure comes from one of them. This page maps what you observe to where it comes from.
Start here
Before guessing at a cause, search the audit log for the patient identifier or the MSH-10 control ID in question. Every message and its acknowledgment are recorded together as one exchange, so the search answers "did it arrive and was it acknowledged" first.
Inbound - a system sending to you
| Symptom | Layer | Where the fix is |
|---|---|---|
| The sender cannot connect at all | The network - port 11553 (11554 for TLS) is not published or a firewall blocks the sender's address | Connectivity and ports |
| The feed is silent - no messages arrive, no errors either | The sender or the channel - connection open and close events appear in the server log per connection, so their absence means the sender never connects | Logging |
The sender receives AR | Routing - no channel's rules match the message and there is no default channel | Routing |
The sender receives AE | Your service raised an exception, or validation rejected the message - the full error is in the server log and the audit log | Acknowledgments |
The sender receives AE but sees no error details | The channel's Return errors toggle is off, which is the production default - the details are on your side, in the logs | Acknowledgments |
The message was accepted (AA) but nothing happened downstream | Your service or its destinations - the audit log's flow view shows every event of that one message, across every system it touched | Audit log views |
| The same message was processed twice | Deduplication - the window is shorter than the sender's retransmission policy, is disabled, or the sender assigns a new MSH-10 on each retry | Deduplication |
| The message fails to parse | The sender's formatting - tolerance repairs handle most non-compliant senders, and Log messages shows the payload before and after preprocessing | Tolerance |
| Names or diacritics arrive garbled | Encoding - the sender's character set differs from what the channel decodes with, MSH-18 detection resolves most of it | Encoding |
| The connection closes with no ACK at all | Framing - the message exceeds the configured maximum size, so the connection is closed | Protocol |
A batch (FHS/BHS) is rejected or parsed wrong | The channel parses batches as single messages - batch channels need Parse on input off | Batch messages |
| The sender insists a message was sent but you cannot find it | The audit log - it records every exchange, searchable by the MSH-10 control ID or a patient identifier | Audit log views |
Outbound - you sending to other systems
| Symptom | Layer | Where the fix is |
|---|---|---|
KeyError on self.mllp[name] | The connection's name, or the connection is inactive | Sending |
| An exception naming a timeout | The remote side answers slower than the connection's Receive timeout - 250 ms by default | Sending |
is_accepted is False with AE | The remote side failed to process the message - error_text contains what it reported | Acknowledgments |
should_retry is True | The remote side asked for a retry (AR or CR) - resubmitting the message as-is can work | Resubmitting messages |
| A destination never acknowledges | The audit log's Outstanding filter lists the exchanges whose acknowledgment has not arrived, oldest first | Audit log views |
| One destination of several missed a message | A hop resend sends the stored payload to that one destination again, without touching the others | Resubmitting messages |
After an outage
An interface that was down and is back up raises its own questions - what queued in the meantime, what to reprocess and what protects the catch-up from double-processing. Downtime and recovery covers that whole path.
Knowing before anyone calls
Alert rules over the audit log tell you that an interface is down, slow or failing - including the feed that simply went silent - before the people downstream notice. Each alert notification links straight to the events that triggered it, and an alert can also be diagnosed by an LLM with the evidence attached and secrets masked.
Where the details are
| Place | What it holds |
|---|---|
| The audit log | Every message with its acknowledgment, searchable by control ID and patient identifier, with the flow of each message across systems |
logs/server.log | Connection events, routing decisions, framing warnings and service tracebacks |
| Log messages on a channel or connection | The full payloads, before and after tolerance preprocessing - development only, HL7 messages contain PHI |
Learn more
Schedule a meaningful demo
Book a demo with an expert who will help you build meaningful systems that match your ambitions
"We evaluated 12 integration platforms and Zato was the only one to score 100%."
Philip Zuñiga, Assistant Professor, University of the Philippines