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.

Overview

Most issues fall into one of the following categories:

• Validation failures during order submission
• Compendium misalignment
• Missing required data or inputs
• Routing or laboratory compatibility issues
• Result retrieval timing or query errors

The sections below describe common issues, their causes, and how to resolve them.

Order Submission Failures

Issue

Order submission fails and returns an OperationOutcome.

Common Causes

• 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

• 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

Issue

Orders are rejected or fail validation despite appearing correct.

Common Causes

• 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

• 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

Issue

Orders are rejected, delayed, or split unexpectedly.

Common Causes

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

Resolution

• 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 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

Issue

Orders fail validation or are not processed correctly.

Common Causes

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

Resolution

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

Required Input (AOE) Issues

Issue

Orders fail validation due to missing or incorrect required inputs.

Common Causes

• Required AOE responses not included
• Incorrect answer format (e.g., free text instead of coded value)
• Missing QuestionnaireResponse reference in ServiceRequest.supportingInfo

Resolution

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

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

Result Retrieval Issues

Issue

No results are returned after order submission.

Common Causes

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

Resolution

• Results are available after laboratory processing completes
• Retrieve results using:
  • DiagnosticReport?based-on=RequestGroup/{order-id}
  • Observation?based-on=RequestGroup/{order-id}
• Confirm that the correct RequestGroup.id is used

Results are not available immediately after order submission and may be delayed depending on laboratory processing time.

Document Retrieval Issues

Issue

Document-based results or files are missing.

Common Causes

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

Resolution

• 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

Issue

No notifications are received.

Common Causes

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

Resolution

• 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 Not Available Immediately

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

Summary

Most issues in Lab Network workflows are caused by validation failures, compendium misalignment, or incorrect assumptions about result timing.

Use OperationOutcome, compendium definitions, and endpoint patterns to diagnose and resolve issues.

Design your workflow to handle:

• Validation errors
• Asynchronous result delivery
• Order separation across laboratories
• Differences in laboratory capabilities