Troubleshoot TEFCA-CommonWell errors

Last updated: Jun 16, 2025

SUPPORT

HEALTH TECH VENDOR

Coming soon

This feature is coming soon, so you won’t see it live in a production environment just yet. Stay tuned for the release!

You may run into errors when interacting with your onramp to TEFCA-CommonWell. Review these common errors and recommendations for fixing them.

If you need extra support to resolve any TEFCA-CommonWell issues, submit a Help Center request.

HTTP error codes

You may see HTTP error codes returned if there’s an issue on the TEFCA side of the data exchange.

Code	Error message	Notes
401 Unauthorized		Your query is probably missing Meta field(s). Remember that metadata is required for every query to TEFCA-CommonWell. Check your log(s) to see if any metadata fields are missing.
403 Forbidden	[OID] already exists.	This means you’re attempting to create a new clinical network organization or patient record with an existing OID. Make sure to use a unique OID.
403 Forbidden	Failed to parse request body as XML resource.	This error occurs because your request body has to have: (a) at least one identifier element; (b) a valid type element; (c) at least one contact element (for implementer only); and (d) valid display names for any configured destinations.
403 Forbidden	id: [ID] is not valid.	This may be returned if you attempt to update or delete an organization record or patient record with an OID that doesn’t currently exist.
500 Internal Server Error	Parsing XML request error!
500 Internal Server Error	Your Organization Source contains a duplicate business!

Organization access not allowed

Error message	Notes
Access to this organization is not allowed -- could not find permission scope.	This means there’s an issue with configuration on the Redox side. Every organization record created in CommonWell-TEFCA must have an associated Data Network Participant Repository (DNPR) setup within Redox. A DNPR links appropriate entities between Redox and CommonWell to provide functionality and permission scopes. Typically, this is configured for you during implementation. Only a Redoxer can manage DNPR setup. Submit a Help Center request to get help with this error. In the request, include your organization OID, your destination ID for document responding, and your supported purpose(s) of use.

Error message

Notes

Access to this organization is not allowed -- could not find permission scope.

This means there’s an issue with configuration on the Redox side. Every organization record created in CommonWell-TEFCA must have an associated Data Network Participant Repository (DNPR) setup within Redox.

A DNPR links appropriate entities between Redox and CommonWell to provide functionality and permission scopes. Typically, this is configured for you during implementation.

Only a Redoxer can manage DNPR setup. Submit a Help Center request to get help with this error. In the request, include your organization OID, your destination ID for document responding, and your supported purpose(s) of use.

No patient search results from another organization

If there aren’t any matches for your patient search, you’ll receive back 200 response with an empty result array.

CommonWell EMPI results

With the CommonWell EMPI, results will only be returned for matches that already exist within your own organization’s data set. In other words, demographics results from external repositories won’t be returned unless a demographics match already exists within your own CommonWell dataset.

To get matches, make sure to register patients of interest in your system before querying in order to get data back. Registration can happen through a PatientAdmin feed or backfill to transfer patients from one clinical network to another.

If you’re not getting matches, it’s possible that data exists in the network but you haven’t registered the patient yet in your system.

If you’re not seeing sandbox patient results when searching for demographics that should exist, it could be because you haven’t first ingested the patient into your own organization. Once the EMPI recognizes your system as knowing about this patient, it will return external matches across other external organizations.

No subscriptions

You may see a subscription error returned if the correct ID is missing from the Meta.Destinations array.

Error message	Notes
No subscriptions. Meta.Destinations needs to contain a destination from existing subscription.	This means we don’t recognize a valid connection. You need to populate the destination ID to indicate where you’re sending your query.

Review the correct destination IDs based on the purpose of the request for both development and production environments.

Destination IDs for TEFCA-CommonWell

Query purpose	Development ID	Production ID
Perform a patient search	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
Query for/create/update/delete an organization	3122bfff-f1fb-4fdf-97de-294f24338229	7fd005ac-d788-40c5-b4e8-b57bb8e310a9
Search for a clinical summary/document	Cf1dca0e-98de-432b-8c9a-dd039816df0e	79981c00-b9c4-40a9-9844-01980e6e524e
Save patient details and documents to your repository	This is specific to your organization. Redox provides the correct ID.	This is specific to your organization. Redox provides the correct ID.

Timeouts and connectivity

You may receive timeout or connectivity errors as different systems undergo maintenance or small outages.

Error message	Notes
Request received a response with status code 504.	Likely due to a system maintenance or outage issue. Retry the request.
Socket hang up	Likely due to a system maintenance or outage issue. Retry the request.
Client network socket disconnected before secure TLS connection was established.	Likely due to a system maintenance or outage issue. Retry the request.

These connectivity errors are typically temporary. If you see persistent problems, submit a Help Center request.

Data on demand error state

You may see an error when sending a PatientAdmin or ClinicalSummary to your data on demand repository.

Error message	Notes
Cannot process messages for Data on Demand environment 'environment', the environment is in a 'error' state.	We work to deliver in a first-in, first-out (FIFO) order so that data arrives in its intended order. Receiving this error indicates that there was an error processing an incoming message. For example, this could happen if you use an invalid patient identifier type. Make sure to use a unique patient OID. At this point, we pause future messages from filing to make sure that the data isn’t missed or corrupted. Submit a Help Center request to reset the environment.

Error message

Notes

Cannot process messages for Data on Demand environment 'environment', the environment is in a 'error' state.

We work to deliver in a first-in, first-out (FIFO) order so that data arrives in its intended order. Receiving this error indicates that there was an error processing an incoming message. For example, this could happen if you use an invalid patient identifier type. Make sure to use a unique patient OID.

At this point, we pause future messages from filing to make sure that the data isn’t missed or corrupted. Submit a Help Center request to reset the environment.

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.