Epic EHR Build Defects: Troubleshooting Guide for Common Errors by Module
Epic build defects follow predictable patterns. The same categories of errors appear across implementations regardless of organization size, Epic version, or implementation scope. Build analysts who know the most common error types and their diagnostic steps resolve defects faster, design better tests, and prevent repeat failures in subsequent cycles. This article covers the highest-frequency Epic build defects by module, explains why they occur, and provides the diagnostic approach that resolves them.
- Why Epic Build Defects Repeat Across Implementations
- Prelude and Registration Build Defects
- Cadence and Scheduling Build Defects
- CPOE and Clinical Decision Support Defects
- ClinDoc and Nursing Documentation Defects
- Willow and Pharmacy Defects
- Bridges Interface and ADT Defects
- Resolute and Charge Capture Defects
- Cogito Reporting Defects
- Defect Prevention: The Build Practices That Matter Most
- Downloads
Why Epic Build Defects Repeat Across Implementations
Most Epic build defects are not novel. They are predictable failures that occur because the build decision that causes them is genuinely ambiguous without implementation experience. A build analyst configuring charge trigger status for the first time faces four options. Without knowing which one is clinically and operationally correct for the specific order type, the wrong choice looks as valid as the right one. The defect is not carelessness – it is the absence of the implementation pattern knowledge that only comes from having made the same mistake before.
Epic’s build environment does not prevent ambiguous configuration. It provides options and expects the build analyst to select the right one. The Six Sigma concept of error-proofing (poka-yoke) does not fully apply here – the system will accept a wrong configuration without flagging it as an error. The wrong charge trigger passes the build. The wrong EMPI threshold passes the build. Only testing – or go-live – reveals the problem. That is why knowing the failure patterns in advance is operationally valuable: it allows analysts to test specifically for the known failure modes rather than discovering them accidentally. The full Epic module architecture that these defects occur within is covered in the Epic EHR Learning Hub.
Prelude and Registration Build Defects
EMPI Threshold Miscalibration
The most common and highest-impact Prelude build defect is EMPI threshold miscalibration. The EMPI probabilistic matching algorithm uses configured score thresholds to decide whether an incoming registration matches an existing patient record. A threshold set too high creates duplicate patient records for patients with minor demographic variations. A threshold set too low auto-links records that belong to different patients.
Why it occurs: The threshold defaults provided by Epic are calibrated for a generic patient population. Every health system’s patient data has different characteristics – name distribution, address format, SSN availability, population size. A threshold that works for a 200-bed community hospital may be wrong for a 5-hospital integrated delivery network.
Diagnostic approach: Run a pre-go-live EMPI match simulation. Extract the existing patient population. Run the EMPI matching algorithm against the population using the proposed thresholds. Measure the false positive rate (incorrect auto-links) and false negative rate (missed matches). Adjust thresholds until both rates are within acceptable tolerance. Do not accept default thresholds without running this simulation.
Test to prevent: Include EMPI test cases that cover exact match, near-match requiring review, non-match for similar demographics, and deliberate duplicate creation scenarios. All four must produce the expected outcome before EMPI configuration is accepted.
Coverage Record Pointing to Wrong Payer Plan
Coverage records migrated from a legacy system may point to incorrect Epic payer plan records if the data mapping was not validated. A coverage record that links to the wrong payer plan produces an incorrect 270 eligibility response and routes claims to the wrong payer in Resolute.
Diagnostic approach: Pull a sample of 100+ migrated coverage records. For each, confirm the Epic payer plan linked to the coverage record matches the payer described in the legacy record. Validate that a 270 eligibility query for each payer returns an expected response.
ADT A04 Not Firing on Registration
When a patient is registered in Prelude, an ADT A04 should fire to downstream systems. If the Bridges interface is configured but not activated, or if a test-mode hold timer was not disabled before go-live, the A04 fires in Epic’s interface log but does not reach downstream systems. Lab and radiology receive no notification of the patient’s existence.
Diagnostic approach: Check the Bridges Interface Monitor immediately after a test registration. Confirm the A04 appears in the outbound message queue with a received ACK from each configured receiving system. If the message is in the queue but no ACK, the receiving system is not processing it. If the message is not in the queue, the interface trigger is not configured or the interface is inactive.
Cadence and Scheduling Build Defects
Provider Template Not Generating Slots
A Cadence provider template that does not generate appointment slots is almost always caused by one of three issues: the template is built but not activated for the correct date range, the template is linked to the wrong department, or the appointment type assigned to the template slots does not match the appointment type the scheduler is using to search.
Diagnostic approach: Open the provider’s template in Cadence. Confirm the template has an active date range that includes the date being searched. Confirm the department on the template matches the department selected during scheduling. Confirm the appointment type on the slots matches exactly what the scheduler is selecting – appointment type names can be similar but distinct in Epic’s build.
SIU Message Not Delivered to Downstream System
Scheduling interface (SIU) messages are sent when appointments are booked, modified, or cancelled. If the SIU interface is not delivering messages to the radiology information system, patient engagement platform, or external scheduling system, the most common causes are: the IFC (interface) record for that connection is inactive, the appointment type is not configured to trigger an SIU message, or the receiving system’s endpoint configuration changed without a corresponding update in Bridges.
Diagnostic approach: Book a test appointment of the specific type in question. Monitor the Bridges SIU interface queue immediately. Confirm the S12 message fires and the ACK returns from the receiving system. If no message fires, check the appointment type configuration for SIU trigger settings. If the message fires but no ACK, check the receiving system endpoint configuration.
CPOE and Clinical Decision Support Defects
Order Routing to Wrong Department Queue
Lab or pharmacy orders routing to the wrong receiving queue is one of the most common CPOE build defects. The routing is determined by the order routing rule – a configuration table that maps the ordering department, the order type, and the patient’s location to the correct receiving department or queue. A routing rule that is missing the correct department combination or uses an incorrect department code produces silent misdirection – the order is placed but arrives in the wrong queue without an error message.
Diagnostic approach: Place a test order of the relevant type from the relevant ordering location. Immediately check the expected receiving queue. If the order is absent, check the Bridges ORM message (for lab orders) to confirm the order transmitted. Then check the order routing rule table for the ordering department and order type combination. The routing rule gap is almost always visible in the configuration once you know which department and order type to look for. CPOE order routing architecture is described in detail in the Epic EHR Orders and CPOE guide.
CDS Alert Firing for Wrong Patient Population
CDS alerts that fire too broadly – for patient populations or order types that should not trigger them – create alert fatigue. A drug-drug interaction alert that fires for a clinically irrelevant combination conditions providers to click through every alert, including the ones that matter. This is a documented patient safety problem, not just a usability complaint.
Why it occurs: CDS alerts are often deployed with the broadest possible scope during build because narrowing the scope requires clinical judgment that build analysts may not have. A drug-drug interaction alert that fires for all patients is easier to configure than one that fires only for patients with specific risk factors. The over-firing is then accepted as “good coverage” rather than recognized as alert fatigue induction.
Diagnostic approach: Measure the alert override rate for each CDS alert type during integrated testing. An override rate above 80% for any alert indicates a scope problem – the alert is firing for situations where the clinical response is always to override. Present the override rate data to the P&T committee and request a scope review. Suppressing low-value alerts is a clinical governance decision, not a build decision, but the analyst must provide the data that drives it.
During Cycle 2 IVT at a 350-bed medical center, an ED physician completing test scenarios reported that she had clicked through 14 CDS alerts to place a single sepsis order set. None of the 14 alerts were ones she would have acted on differently – 11 were drug-drug interaction alerts for combinations routinely used in sepsis management, two were duplicate therapy alerts for medications that were clinically appropriate to give simultaneously, and one was an age-related dosing alert for an adult patient within normal parameters. The analyst team had deployed all CDS alerts in the Epic content library without a P&T review. The P&T committee met within 48 hours of the escalation. They suppressed 9 of the 14 alert types for the ED patient population, converted 3 to passive Best Practice Advisories rather than hard-stop alerts, and retained 2 as hard stops for documented patient safety reasons. The sepsis order set then required 2 alert acknowledgments – both clinically relevant.
Order Set Content Not Matching Clinical Protocol
Order sets built without direct physician or pharmacist review frequently contain dosing defaults, frequency settings, or medication options that do not match the organization’s adopted clinical protocol. A sepsis order set with a generic antibiotic default instead of the organization’s formulary-preferred antibiotic causes providers to modify every order every time – which increases order entry time and introduces transcription risk.
Resolution: Every order set must be reviewed by the clinical champion for that condition before it is activated. “Reviewed” means a physician or pharmacist opened the order set in the test environment and confirmed each order against the source protocol document, not just approved a written description of what the order set was supposed to contain.
ClinDoc and Nursing Documentation Defects
Wrong Flowsheet Loading for a Care Area
When the wrong nursing flowsheet loads after a patient is assigned to a bed, the cause is almost always a mismatch between the department/unit configured in the flowsheet assignment record and the actual department where the patient is located in Epic’s bed master. An ICU flowsheet loading for a medical-surgical patient is not visible as an error in the build – it only surfaces when a nurse opens the flowsheet and sees the wrong configuration. Common documentation defects are addressed in the EpicCare Inpatient ClinDoc guide.
Diagnostic approach: Register a test patient, assign to a specific bed, and immediately open the nursing flowsheet. Confirm the flowsheet displayed matches the unit type. If it does not, open the flowsheet assignment master record and verify the department linked to the flowsheet matches the department master record for the unit in question. The mapping is a direct lookup – department ID in the flowsheet assignment must exactly match the department ID in the bed master.
Note Template Not Triggering Charge Event
When a provider signs a note but no charge appears in the charge lag report, the most common cause is that the documentation template was not linked to the charge event in Epic’s template configuration. A note template that is correctly built and signed by providers generates no charge if the charge trigger connection was never established.
Diagnostic approach: Sign a test note using the specific template. Wait 5 minutes (for near-real-time Clarity if using charge monitoring reports). Check the charge lag report or the charge review queue for the ordering provider and encounter. If no charge: open the template configuration and confirm the charge trigger is linked. The linkage is usually a single field in the template record – if it is blank, no charge will ever fire regardless of how many times the note is signed.
SmartPhrase or SmartLink Not Populating
SmartPhrases and SmartLinks that do not resolve when a provider types the trigger text are caused by one of three issues: the SmartPhrase/SmartLink is not published (it remains in draft state), the provider does not have the SmartPhrase in their context (department, role, or specialty filter is too restrictive), or the trigger text has a typo in the configuration.
Diagnostic approach: In the ClinDoc SmartPhrase management, confirm the SmartPhrase status is Published, not Draft. Confirm the context filter allows the provider’s department or role. Test the trigger text exactly as configured – a difference between a period-prefixed trigger and a non-period trigger will cause the phrase not to resolve.
Willow and Pharmacy Build Defects
Medication Order Routing to Wrong Pharmacy Queue
A medication order that routes to the wrong pharmacy queue (e.g., general inpatient pharmacy instead of oncology pharmacy) is caused by a gap in the medication routing rules in Willow. The routing rule maps the ordering department, the medication type, and in some cases the patient’s location to the correct pharmacy queue. A missing department in the routing table produces the wrong routing silently – the pharmacist in the wrong queue verifies the order, or worse, the order sits in an unmonitored queue.
Diagnostic approach: Place a test order of the specific medication type from the specific ordering department. Immediately check the expected pharmacy queue. If absent, check the routing rule table for that department-medication type combination. Add the missing department to the routing rule and retest.
BCMA Barcode Scan Fails – Medication Not Found
A BCMA barcode scan that returns “medication not found” or “no active orders” is caused by an NDC (National Drug Code) barcode that is not mapped to the drug record in Willow. The physical medication label has a barcode that the scanner reads. If that NDC is not in Epic’s drug barcode table for that medication, the system cannot match the physical medication to the order.
Diagnostic approach: Scan the barcode in a test BCMA session and note the NDC returned by the scanner. Search for that NDC in the Willow drug barcode master. If the NDC is absent, add it to the drug record’s NDC list. NDC coverage is an ongoing maintenance activity – new drug lot numbers with different NDCs arrive regularly, and each must be added to Epic’s drug barcode table before staff can scan that specific medication lot.
ADC Cabinet Not Updating After Admit
The ADC (Automated Dispensing Cabinet) should update with the admitted patient’s active medications when an ADT A01 fires. If the ADC does not update after admission, the cause is either ADT A01 latency (the Bridges interface held the message) or the ADC cabinet is not mapped to the patient’s assigned bed in the ADC-to-bed assignment configuration.
Diagnostic approach: Admit a test patient to a specific bed. Check the Bridges Interface Monitor – confirm the ADT A01 fired and the ACK was received from the ADC system within the expected latency window. If A01 fired and was acknowledged but the ADC did not update, the patient’s bed is likely not mapped to the correct ADC cabinet in the cabinet-to-bed assignment table. If the A01 did not fire or was delayed, check for hold timers in the Bridges interface configuration.
Bridges Interface and ADT Build Defects
PID Segment Field Mismatch in ADT Messages
HL7 ADT messages carry patient demographics in the PID segment. When a downstream system rejects an ADT message or a patient does not appear correctly in a receiving system, the most common cause is a PID field mismatch – the assigning authority for the patient ID, the format of the date of birth, or the name component order does not match what the receiving system expects.
Diagnostic approach: Extract a raw HL7 message from the Bridges Interface Monitor for the failing transaction. Compare the PID segment field by field against the receiving system’s HL7 interface specification. HL7 v2 is flexible enough that two systems can both be “HL7 compliant” while having incompatible field formats. The receiving system’s vendor spec is the authoritative reference – not Epic’s default output format.
Message Accumulating in Error Queue
Messages accumulating in the Bridges error queue without being processed indicates a receiving system that is returning NACK (negative acknowledgment) for a field it cannot process, or a network connectivity failure preventing delivery. Error queue accumulation is a silent problem – Epic’s clinical workflow continues normally while the downstream system falls increasingly out of sync.
Diagnostic approach: Open the Bridges Interface Monitor error queue. Examine the error reason for the first failed message. HL7 NACK messages include an error code that identifies which field failed. Address the field formatting issue, reprocess the queued messages, and confirm the queue clears. Establish an Interface Monitor monitoring alert that notifies the integration analyst when the error queue exceeds a defined threshold – the problem should be caught within minutes, not days.
Three days after go-live at a community hospital, the laboratory team reported that patient names were appearing incorrectly formatted in the LIS – middle names were being truncated and some international name characters were displaying as garbled text. Investigation of the Bridges error queue revealed 847 ADT messages had accumulated over 72 hours with partial processing. The LIS was accepting the messages but logging errors for the name field format. The root cause: Epic’s PID.5 segment was sending names in Last^First^Middle format, but the LIS expected Last^First format with no middle name component. The middle name was being interpreted as a suffix by the LIS, causing both the truncation and the character rendering issue. The fix was a Bridges transform rule that stripped the middle name component from the PID.5 field for that specific interface. The 847 queued messages were reprocessed after the fix. The monitoring alert that would have caught this on day one had not been configured before go-live.
Resolute and Charge Capture Build Defects
Charge Not Firing for Clinical Action
Missing charges are the highest-frequency billing defect. The charge trigger is configured at the order or documentation level – it specifies which clinical workflow action (order placed, order resulted, note signed, administration documented) fires the charge. A charge trigger set to the wrong status fires at the wrong time or not at all.
| Charge Trigger Status | Fires When | Correct Use Case | Common Mistake |
|---|---|---|---|
| Ordered | Order is placed and signed | Rarely correct – charges at order not delivery | Used for labs/imaging – causes charge before service delivered |
| Resulted | Order is resulted/finalized | Lab tests, radiology interpretations | Sometimes missed for radiology – read not same as ordered |
| Administered | Medication documented as given in eMAR | Infusions, injections, IV medications | Set to “Ordered” for infusions – charge fires even if cancelled |
| Completed | Procedure/visit is completed and signed | E/M visits, procedures with documentation | Note template not linked – charge never fires despite correct trigger |
Diagnostic approach: Check the charge lag report. For any order type showing missing charges, identify the order, open the CDM item linked to that order, and check the charge trigger status field. Compare it to the expected trigger status for the service type. If the trigger is correct, check whether the clinical workflow step that should fire it actually completed (e.g., was the note actually signed, was the result actually verified).
Duplicate Charges for the Same Service
Duplicate charges occur when charge triggers are configured at multiple status levels for the same order. A lab order configured with charge triggers at both “Ordered” and “Resulted” will generate two charges – one when the order is placed and a second when the result posts. Both charges look valid individually but represent a duplicate billing risk.
Diagnostic approach: Pull the charge report for a specific order type. If the same CDM item appears twice for the same encounter and same order, open the order’s CDM configuration and inspect all charge trigger points. Remove the incorrect trigger while retaining the clinically appropriate one. This defect is common when two analysts have worked on the same CDM item without coordinating, or when a default trigger is retained alongside a custom one.
Cogito Reporting Build Defects
Report Shows Stale Data Despite Recent Clinical Actions
A Reporting Workbench report that does not reflect recent clinical actions is almost always a Clarity ETL timing problem – not a report logic error. If the report is built on a Clarity table that runs on a nightly extract schedule, it will not show same-day data until the extract runs. Operational dashboards that need near-real-time data must be built on Clarity tables configured for the near-real-time extract schedule.
Diagnostic approach: Identify which Clarity table the report queries. Check the ETL schedule for that table. If the table is on a nightly cycle and the report needs same-day data, the fix is to switch the ETL schedule for that table to near-real-time – not to rebuild the report. This is an infrastructure configuration change, not a report logic fix.
Shipped Report Using Wrong Metric Definition
Epic’s shipped Reporting Workbench reports are starting points, not validated metrics. A CMS quality measure report that uses a slightly different denominator definition than CMS’s official measure specification will produce a different result from what CMS calculates at submission. The difference may be small in testing but creates significant discrepancies at scale.
Resolution: Every shipped report used for external reporting must be validated against the official metric specification before go-live. This means opening the CMS, Joint Commission, or accreditation body’s published measure specification and comparing it field by field against the report’s denominator, numerator, and exclusion logic. The validation must be documented for the record.
Defect Prevention: The Build Practices That Matter Most
The majority of recurring Epic build defects are preventable through three practices that most teams skip under schedule pressure: cross-module build review before integrated testing, boundary-value testing for configuration thresholds, and Interface Monitor monitoring from day one of go-live.
| Defect Category | Most Common Root Cause | Prevention Practice | Detection Test |
|---|---|---|---|
| EMPI duplicate records | Default threshold not calibrated to actual population | Pre-go-live match simulation against production-equivalent data | 4-case EMPI test: exact, near, non, deliberate dup |
| Wrong order routing | Routing rule table missing department combination | Routing rule completeness check per order type per department | Place order from every relevant dept, check queue immediately |
| CDS alert fatigue | Alerts deployed without P&T scope review | P&T review of every CDS alert before activation | Override rate monitoring – flag any alert over 80% |
| Missing charges | Wrong charge trigger status or missing template link | Charge trigger status reviewed per order type before IVT | Charge lag report checked after every clinical action in testing |
| BCMA barcode failure | NDC not mapped in drug barcode table | NDC coverage validated for all formulary medications before IVT | Scan physical medication barcode for every drug type in testing |
| ADT interface error queue | PID field mismatch between Epic and receiving system spec | Raw HL7 message reviewed against vendor spec before go-live | Interface Monitor baseline established and monitored daily from day 1 |
| Stale Cogito report data | Nightly ETL on table needing near-real-time data | ETL schedule reviewed per reporting use case latency requirement | Place clinical action, wait for extract window, check report |
Defect patterns that repeat across implementations indicate a systemic gap in build review processes – not individual analyst failures. The BAT and UAT testing frameworks that catch these defects before go-live are described in the BAT vs UAT guide. The go-live command center model that catches defects that escape testing is covered in the Epic EHR Go-Live Support framework.
Configure the Bridges Interface Monitor alert threshold before go-live and have someone watch it for the first 72 hours. Most interface defects that surface at go-live were present during integrated testing but were not caught because nobody was monitoring the error queue in real time. A single analyst with Interface Monitor access and a documented baseline message count can identify and escalate every interface failure within minutes of occurrence – before it creates a downstream patient care impact that takes hours to unravel.
Authoritative References
- HL7 v2.x Messaging Standard – ADT Message Specifications: PID, PV1, and OBR Segment Definitions
- ISTQB – Certified Tester Foundation Level Syllabus: Defect Classification, Root Cause Analysis, and Error Prevention