HL7 ERR Segment: Error

ERR reports an error condition detected while processing a message. It almost always travels inside an acknowledgement: when a receiver cannot accept or apply a message, it returns an ACK whose MSA carries the rejection code and whose ERR segment(s) carry the detail — where the error is, what kind it is, how severe it is, and a human-readable description. A single response may contain multiple ERR segments, one per problem found. ERR was heavily restructured in v2.5: the old free-text single-field ERR-1 was replaced with a set of structured fields (error location, coded error code, severity, application error code, diagnostics, help text), so the shape of ERR depends strongly on the version in play.

Purpose

ERR carries the specifics of a processing error so the sender can understand and act on a rejection or warning. It identifies the location of the offending field, classifies the error with an HL7 code and a severity, optionally adds an application-specific code, and supplies diagnostic and user-facing text. MSA gives the overall accept/reject verdict; ERR explains why.

Used in

ERR appears in acknowledgement and error responses across most message types. It is most common in the general ACK and in application-level negative acknowledgements, where it accompanies an MSA with an error or reject code. See ACK messages for the response structure that carries ERR. Any message that can be acknowledged can elicit an ERR in its response.

Field-by-field reference

No segment-level ConceptMap is published in the v2-to-FHIR IG for ERR. The fields below are taken from the HL7 v2.5.1 standard. R = required (cardinality min ≥ 1). Repeat = field may repeat. Length is not reproduced here. Table # is shown only where well-established.

The required flags above follow the HL7 v2.5.1 standard, where ERR-3 (HL7 Error Code) and ERR-4 (Severity) are the required fields. ERR-1 is the deprecated legacy field; treat its presence as a sign of an older sender.

Most-used fields

ERR-2 Error Location is the field integrators reach for first when debugging: it points at the exact segment and field that failed, e.g. PID^1^7 meaning the seventh field of the first PID. ERR-3 HL7 Error Code classifies the failure with a standard code such as 101 (required field missing) or 204 (unknown key identifier). ERR-4 Severity decides how the sender should react — E and F are hard failures, W and I are advisory. ERR-7 Diagnostic Information and ERR-8 User Message carry the text a support engineer and an end user respectively will read.

Version differences (2.3 to 2.8.2)

• 2.3 / 2.3.1 / 2.4: ERR had a single repeating field, ERR-1 Error Code and Location (an ELD-typed field), carrying location and code together as free-ish text. There was no separate severity, application error code, or structured location.
• 2.5 / 2.5.1: ERR was heavily restructured. ERR-1 was retained but deprecated, and the structured fields ERR-2 (Error Location), ERR-3 (HL7 Error Code), ERR-4 (Severity), ERR-5 (Application Error Code), ERR-6 through ERR-12 were introduced. This is the version this page documents.
• 2.6 / 2.7 / 2.8 / 2.8.2: the v2.5 structure carries forward with refinements to data types and the supporting code tables. Receivers built for 2.3/2.4 that only understand ERR-1 will not parse the structured fields; senders that must interoperate with old systems sometimes populate both ERR-1 and the new fields.

Common mistakes

• Reading or producing ERR-1 (deprecated) instead of the structured ERR-2 through ERR-5 on a v2.5+ interface.
• Omitting ERR-3 or ERR-4 — both are required in v2.5.1; an ERR without an HL7 error code and severity is non-conformant.
• Confusing severity with the acknowledgement verdict. MSA-1 carries accept/reject; ERR-4 only describes the severity of one error and does not by itself reject the message.
• Putting developer diagnostics in ERR-8 User Message (shown to clinicians) instead of ERR-7 Diagnostic Information.
• Sending a single ERR with concatenated text when several distinct problems should be several repeating ERR segments.

Examples

Minimal valid ERR (required fields only — HL7 error code and severity):

ERR||PID^1^7|101^Required field missing^HL70357|E

Fully-populated ERR:

ERR||PID^1^7&1|101^Required field missing^HL70357|E|207^Application internal error^HL70533|param1|Field PID-7 (Date of Birth) was empty|Patient date of birth is required to admit|U^User^HL70517||

Annotated breakdown of the minimal example:

ERR                             ← segment ID
                                ← ERR-1  Error Code and Location (deprecated, empty)
PID^1^7                         ← ERR-2  Error Location (segment PID, sequence 1, field 7)
101^Required field missing^HL70357  ← ERR-3  HL7 Error Code (CWE from HL70357)
E                               ← ERR-4  Severity (E = error)

In-context inside a general ACK rejecting a message:

MSH|^~&|RECV|HOSP_B|EPIC|HOSP_A|20260609120500||ACK^A01^ACK|CTRL-ACK-0001|P|2.5.1
MSA|AE|MSG00001|Message rejected: required field missing
ERR||PID^1^7|101^Required field missing^HL70357|E|||Field PID-7 (Date of Birth) was empty|Patient date of birth is required

In-context inside an application acknowledgement with two errors:

MSH|^~&|LAB|HOSP_B|EHR|HOSP_A|20260609131500||ACK^R01^ACK|CTRL-ACK-9931|P|2.5.1
MSA|AR|CTRL-9931|Order rejected
ERR||ORC^1^2|204^Unknown key identifier^HL70357|E|||Placer order number not found
ERR||OBR^1^4|103^Table value not found^HL70357|W|||Test code CBC not in catalog

FHIR mapping

No segment-level ConceptMap is published in the v2-to-FHIR IG for ERR (it is not listed in the segment maps index). The conventional FHIR analogue is OperationOutcome.issue, where one ERR segment corresponds to one OperationOutcome.issue entry. The table below is descriptive guidance, not an official IG mapping.

ERR-1 (deprecated), ERR-6, ERR-9, ERR-10, ERR-11, and ERR-12 have no clean OperationOutcome target and are typically dropped or folded into diagnostics when an engine emits an OperationOutcome.

Engine considerations

• Treat repeating ERR segments as a list: emit one entry per distinct problem rather than concatenating text into one ERR.
• Always populate ERR-3 and ERR-4 when producing ERR on a v2.5+ interface; downstream validators and trading-partner conformance profiles expect both.
• Map ERR-4 severity carefully when bridging to FHIR — v2 has four values (W, I, E, F) while OperationOutcome.issue.severity has fatal/error/warning/information; collapse E to error and F to fatal.
• When consuming an ACK, read MSA-1 for the verdict first, then walk the ERR segments for detail. An older partner may send only ERR-1; fall back to parsing it if ERR-2 through ERR-5 are absent.
• Keep ERR-7 (diagnostics) and ERR-8 (user message) on separate channels; surfacing raw diagnostics to clinicians is a common usability and safety complaint.

How Vorro parses and produces ERR

On the consume side, Vorro reads MSA-1 to determine the acknowledgement verdict, then iterates every ERR segment, capturing ERR-2 location, ERR-3 code, and ERR-4 severity into a structured error list for routing, alerting, and retry decisions. On the produce side, when Vorro rejects an inbound message it emits an ACK with a matching MSA and one ERR per detected problem, always setting ERR-3 and ERR-4, placing engineer-facing detail in ERR-7 and user-facing text in ERR-8, and pointing ERR-2 at the precise failing field. For partners on pre-2.5 interfaces, Vorro can additionally populate the legacy ERR-1 so older receivers still see the error.

Related pages

• MSA — the acknowledgement segment whose verdict ERR explains.
• MSH — the message header that opens every ACK carrying ERR.
• ACK messages — the response structure where ERR appears.

Sources

• HL7 v2-to-FHIR IG — segment maps index — confirms no ERR segment ConceptMap is published
• HL7 Version 2.5.1 product brief