Error guide & FAQ

Plain-language explanations of the messages the FHIR validator produces, grouped by category. The same explanations appear on each issue in your validation results.

Troubleshooting & FAQ

9 entries

Contained resource problem References

What it means: A contained resource is unreferenced, duplicated, or not a FHIR resource.
Why: Contained resources must be used and uniquely identified.
How to fix: Reference it as #id from the parent, or remove it.

"contained": [ { "resourceType": "Medication", "id": "m1" } ], "medicationReference": { "reference": "#m1" }

Validator message IDs: CONTAINED_ORPHAN_DOM3 Contained_resource_does_not_appear_to_be_a_FHIR_resource_unknown_name_ RESOURCE_DUPLICATE_CONTAINED_ID

Malformed reference References

What it means: reference is not a valid relative or absolute URL.
Why: Receivers resolve references literally.
How to fix: Use ResourceType/id (no spaces, no extra path) or an absolute URL.

"reference": "Patient/pat-0001"

Validator message IDs: REFERENCE_REF_INVALID_REF REFERENCE_REF_QUERY_INVALID REFERENCE_REF_SUSPICIOUS Reference_REF_Format1 Reference_REF_Format2

Reference cannot be resolved References

What it means: The reference at the reported location points to a resource the validator could not find.
Why: A dangling reference leaves the record incomplete.
How to fix: Include the target resource (in the same Bundle with a matching fullUrl, or contained), or make sure the reference is Type/id of an existing resource.

"subject": { "reference": "Patient/pat-0001" }

Validator message IDs: Reference_REF_CantResolve Unable_to_resolve_reference_to_ reference_to__cannot_be_resolved

Reference matches several Bundle entries References

What it means: More than one entry matches the reference.
Why: Ambiguous references cannot be resolved safely.
How to fix: Give each entry a unique fullUrl.

Validator message IDs: BUNDLE_BUNDLE_ENTRY_FOUND_MULTIPLE BUNDLE_BUNDLE_ENTRY_FOUND_MULTIPLE_FRAGMENT Bundle_BUNDLE_MultipleMatches

Reference points to the wrong resource type References

What it means: The reference at the reported location targets a resource type (or profile) that the element does not allow.
Why: Profiles restrict targets so data forms the intended model (for example a performer must be a Practitioner).
How to fix: Reference a resource of an allowed type listed in the message.

"performer": [ { "reference": "Practitioner/prac-01" } ]

Validator message IDs: Bundle_BUNDLE_Entry_Type2 REFERENCE_REF_WRONGTARGET_LOAD Reference_REF_BadTargetType Reference_REF_BadTargetType2 Reference_REF_ResourceType Reference_REF_WrongTarget

Reference type unknown or display missing References

What it means: The target type can't be determined, or the reference carries neither a link nor an identifier.
Why: An empty reference tells receivers nothing.
How to fix: Provide reference (preferred) or identifier, optionally display.

Validator message IDs: Reference_REF_Aggregation Reference_REF_NoDisplay Reference_REF_NoType

Referenced entry not found in the Bundle References

What it means: A reference inside the Bundle does not match any entry's fullUrl.
Why: References in a Bundle are resolved by fullUrl, not by id alone.
How to fix: Make reference equal the target entry's fullUrl (e.g. urn:uuid:...), or include the target entry.

{ "fullUrl": "urn:uuid:11111111-...", "resource": { "resourceType": "Patient" } }
... "subject": { "reference": "urn:uuid:11111111-..." }

Validator message IDs: BUNDLE_BUNDLE_ENTRY_NOTFOUND_APPARENT BUNDLE_BUNDLE_ENTRY_NOTFOUND_CANNOT BUNDLE_BUNDLE_ENTRY_NOTFOUND_FRAGMENT BUNDLE_BUNDLE_POSSIBLE_MATCH_NO_FU BUNDLE_BUNDLE_POSSIBLE_MATCH_WRONG_FU BUNDLE_POSSSIBLE_MATCHES Bundle_BUNDLE_Entry_NotFound Reference_REF_NotFound_Bundle

Relative reference cannot be resolved References

What it means: A relative or conditional reference cannot be resolved in this context.
Why: Needs a fullUrl or a transaction.
How to fix: Add fullUrl to every Bundle entry, and use conditional references only in transaction bundles.

Validator message IDs: Bundle_BUNDLE_FullUrl_Missing REFERENCE_REF_QUERY_NOT_TRANSACTION REFERENCE_REF_REL_UNSOLVEABLE

urn reference not in Bundle References

What it means: A urn: reference points outside this Bundle.
Why: urn references only work within the same Bundle.
How to fix: Include the target entry in the Bundle.

Validator message IDs: Bundle_BUNDLE_Not_Local