Troubleshooting Labs

Troubleshooting addresses common issues encountered when submitting laboratory orders and retrieving results through Lab Network.

Most issues occur during validation, routing, or result retrieval and can be diagnosed using error responses, compendium alignment, and endpoint behavior.

Finding Your Issue

Each row names a symptom and the section that covers it.

Order Submission Failures

Symptom: Order submission fails and returns an OperationOutcome.

Common causes: Any of the following rejects an order at submission:

• Invalid or unsupported test codes
• Missing required fields
• Missing required inputs for specific tests
• Specimen requirements not met
• Incorrect or incomplete references: patient, practitioner, organization

Resolution: Work through these in order:

• Verify that all test codes exist in the selected laboratory's compendium.
• Ensure all required fields and references are included.
• Provide required inputs for tests that require additional data.
• Confirm specimen requirements and include a Specimen resource when needed.
• Review the OperationOutcome details for specific error messages.

Example error response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Missing required field: performer"
    }
  ]
}

Compendium Misalignment

Symptom: Orders are rejected or fail validation despite appearing correct.

Common causes: The order and the laboratory's compendium disagree:

• Using internal test codes instead of laboratory-specific codes
• Outdated compendium mappings
• Tests not available for the selected laboratory
• Required inputs missing for specific tests

Resolution: Realign the order with the compendium:

• Map all test codes to the selected laboratory's compendium.
• Update mappings to reflect current compendium definitions.
• Confirm that the selected laboratory supports the requested tests.
• Provide all required inputs defined by the compendium.

Order Routing and Splitting Issues

Symptom: Orders are rejected, delayed, or split unexpectedly.

Common causes: Routing constraints prevent a single laboratory from fulfilling the order:

• Tests in the same order require different laboratories.
• Selected laboratory does not support all requested tests.
• Routing configuration constraints

Resolution: Align the order with what one laboratory can fulfill:

• Ensure all tests in an order can be fulfilled by the same laboratory.
• Split orders when tests belong to different laboratories.
• Expect Lab Network to split orders when necessary.

When splitting occurs: A split changes what you track:

• A single submitted order may result in multiple RequestGroup resources.
• Each resulting order must be tracked and managed independently.
• Confirm routing behavior for your configuration.

Specimen Issues

Symptom: Orders fail validation or are not processed correctly.

Common causes: Specimen data is missing or does not match what the test requires:

• Missing specimen data for tests that require it
• Incorrect specimen type
• Incomplete collection details

Resolution: Supply the specimen detail the compendium expects:

• Include a Specimen resource when required.
• Ensure specimen type matches compendium requirements.
• Provide all required collection details.

Required AOE Input Issues

Symptom: Orders fail validation due to missing or incorrect required inputs.

Common causes: Ask-at-order-entry responses are absent or malformed:

• Required AOE responses not included
• Incorrect answer format, for example free text instead of a coded value
• Missing QuestionnaireResponse reference in ServiceRequest.supportingInfo

Resolution: Retrieve and supply the responses the test requires:

• Retrieve required AOE questions for the selected test.
• Provide responses using the correct data type: coding, boolean, date, and so on.
• Ensure the QuestionnaireResponse is included and properly referenced.

Missing or invalid AOE responses are a common cause of order validation failure.

Result Retrieval Issues

Symptom: No results are returned after order submission.

Common causes: The results are not ready, or the query does not match them:

• Results are not yet available.
• Incorrect query parameters
• Using the wrong resource or search criteria

Resolution: Confirm timing first, then the query:

• Results are available after laboratory processing completes.
• Retrieve the report with DiagnosticReport?based-on={order-id}, and add _include=DiagnosticReport:result to return its discrete values in the same bundle.
• Confirm that the correct order identifier is used. The search matches on the order identifier itself, so a resource-type prefix is not required.
• Observation does not support a based-on search. Reach discrete values through the report's result references, or search Observation by patient.

Results are retrieved through API-based endpoints and are not available immediately after order submission.

Results on an Unexpected Patient

Symptom: A result arrives under a patient record you do not recognize, or a result you expected on a known patient never appears, while the ordering provider is correct.

Common causes: Lab Network resolves the provider and the patient separately and resolves the patient last, so a result can reach the right provider and still not reach the right patient:

• The result's demographics did not match an existing record, so a new patient record was created and the result was filed under it.
• The result carried none of postal code, phone number, or Social Security number, which prevents the demographic search from running at all.
• Your organization already holds more than one record for the same person, and the result was filed under a different one than expected.
• Demographics were incomplete, so the result is held in the Unassigned Queue and was never delivered.

Resolution: Reconcile what arrived, then reduce recurrence:

• Reconcile incoming results by their demographic fields rather than by assuming the patient identifier is already known to your system.
• Contact Health Gorilla to have duplicate patient records merged.
• Review the Unassigned Queue in the Lab Network UI for results that were never delivered.
• Include a consistent patient identifier, a complete date of birth, a full legal given name, and at least one of postal code, phone number, or Social Security number on inbound results.

Result Routing and Matching describes the full sequence and every outcome.

Document Retrieval Issues

Symptom: Document-based results or files are missing.

Common causes: The laboratory does not send documents, or the query misses them:

• Laboratory does not provide document-based results.
• Incorrect patient or category filter
• Missing Binary retrieval step

Resolution: Query for the document, then retrieve its content:

• Query DocumentReference using the correct patient and category.
• Retrieve file content using the associated Binary resource.
• Confirm whether the laboratory provides document artifacts.

Subscription Issues

Symptom: No notifications are received.

Common causes: The subscription is inactive, unreachable, or does not match:

• Subscription not created or not active
• Incorrect endpoint configuration
• Event criteria not matching returned data

Resolution: Check the subscription, the endpoint, then the criteria:

• Verify that the Subscription resource is active.
• Confirm that your endpoint is reachable and accepts requests.
• Validate the subscription criteria.
• Check that results meet the criteria, for example status=final.

Common Workflow Issues

Results are not available immediately. Results are delivered asynchronously after laboratory processing. Wait for processing to complete or use subscriptions to receive notifications.