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, or your service raised an exception - the full error is in the server log and the audit log | Routing |
The sender receives AE | Your service raised HL7ApplicationError, or validation rejected the message - the full error is in the server log and the audit log | Acknowledgments |
The sender receives AE or AR 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.
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