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

16 entries

A code is required but none was provided Codes & terminology

What it means: the element is bound to a value set but contains no code (only free text, or an empty coding).
Why: Free text cannot be aggregated or exchanged reliably.
How to fix: Add a coding with system and code from the bound value set. You can keep text as well.

"code": { "coding": [ { "system": "...", "code": "..." } ], "text": "Free text" }

Validator message IDs: Terminology_TX_Binding_Missing Terminology_TX_Binding_Missing2 Terminology_TX_Code_ValueSet Terminology_TX_Code_ValueSetMax Terminology_TX_Code_ValueSet_Ext Terminology_TX_Code_ValueSet_MISSING Terminology_TX_Code_ValueSet_XVER_SOURCE

Code could not be checked Codes & terminology

What it means: The validator has no terminology data to check this code or binding.
Why: The code is not necessarily wrong; the check was skipped.
How to fix: Make sure the code system is a standard one (SNOMED CT, LOINC, ICD-11) or an NP Core code system, and that the code is spelled correctly.

Validator message IDs: Error_expanding_ValueSet_running_without_terminology_services Error_validating_code_running_without_terminology_services Terminology_TX_Binding_CantCheck Terminology_TX_Binding_NoServer Terminology_TX_Binding_NoSource Terminology_TX_NoValid_15

Code has wrong case or form Codes & terminology

What it means: The code is valid except for letter case or its normal form.
Why: Codes are case-sensitive in FHIR.
How to fix: Use the code exactly as published in the code system.

Validator message IDs: CODE_CASE_DIFFERENCE CODE_NOT_IN_NORMAL_FORM

Code is not a valid value for this required binding Codes & terminology

What it means: The element is bound to a small, fixed list of codes and the value you sent is not on it, so the validator could not even tell which code system it belongs to.
Why: Required bindings accept only the listed codes, spelled exactly (lower case, hyphens as published).
How to fix: Open the value set named in the companion message and send one of its codes exactly. Example: Encounter.status uses planned, arrived, in-progress, finished... (not done).

"status": "finished"

Validator message IDs: UNABLE_TO_INFER_CODESYSTEM

Code is not in the recommended value set Codes & terminology

What it means: None of the codings in this CodeableConcept belong to the value set bound to the element. The binding is only extensible/preferred, so this is a warning or note, not an error.
Why: Extensible means: use a code from the value set when one fits; another code is allowed only if no suitable one exists.
How to fix: If a suitable code exists in the named value set, use it. Otherwise keep your code and add text.

Validator message IDs: Terminology_TX_NoValid_1 Terminology_TX_NoValid_2_CC Terminology_TX_NoValid_3_CC Terminology_TX_NoValid_4_CC Terminology_TX_NoValid_5_CC Terminology_TX_NoValid_6_CC

Code is not in the required value set Codes & terminology

What it means: The code at the reported location is not a member of the value set bound to this element.
Why: Value sets guarantee all systems use the same vocabulary so data can be compared and reported nationally.
How to fix: Pick a code from the bound value set (the message names it, and the IG page lists its codes). Make sure system and code belong together.

"code": { "coding": [ { "system": "<code system URL>", "code": "<code from the value set>", "display": "<its display>" } ] }

Validator message IDs: Terminology_TX_Confirm_4a Terminology_TX_Confirm_5 Terminology_TX_Confirm_6 Terminology_TX_NoValid_12 Terminology_TX_NoValid_13 Terminology_TX_NoValid_14 Terminology_TX_NoValid_16 Terminology_TX_NoValid_17 Terminology_TX_NoValid_18 Terminology_TX_NoValid_1_CC Terminology_TX_NoValid_2 Terminology_TX_NoValid_3 Terminology_TX_NoValid_4 Terminology_TX_NoValid_5 Terminology_TX_NoValid_6

Code system version required Codes & terminology

What it means: This code system requires a version on the coding.
Why: Code meaning can change between versions.
How to fix: Add version to the Coding.

Validator message IDs: CODESYSTEM_VERSION_NEEDED

Coding has no system Codes & terminology

What it means: A code without a system URL has no defined meaning.
Why: Receivers cannot know which vocabulary the code belongs to.
How to fix: Add system next to code. If you only have text, use CodeableConcept.text.

{ "system": "http://loinc.org", "code": "8867-4" }

Validator message IDs: Coding_has_no_system__cannot_validate Coding_has_no_system_or_code__cannot_validate

Could not confirm codes are in the value set Codes & terminology

What it means: None of the codings in this CodeableConcept could be confirmed as members of the bound value set (or the maximum value set).
Why: At least one coding must come from the bound value set for the data to be comparable.
How to fix: Add a coding from the value set. Keep local codes only as additional codings next to it.

Validator message IDs: Terminology_TX_Confirm_1_CC Terminology_TX_Confirm_2_CC Terminology_TX_Confirm_3_CC Terminology_TX_NoValid_10 Terminology_TX_NoValid_11 Terminology_TX_NoValid_7 Terminology_TX_NoValid_8 Terminology_TX_NoValid_9

Display text does not match the code Codes & terminology

What it means: display is not the official display name for that code.
Why: A mismatching display suggests the wrong code was picked.
How to fix: Copy the display from the code system, or omit display (it is optional). Verify the code is the one you intended.

Validator message IDs: Display_Name_Not_Fixed_use_Supplement Display_Name_WS_for__should_be_one_of__instead_of Display_Name_for__should_be_one_of__instead_of NO_VALID_DISPLAY_AT_ALL NO_VALID_DISPLAY_FOUND NO_VALID_DISPLAY_FOUND_LANG_NONE NO_VALID_DISPLAY_FOUND_LANG_SOME NO_VALID_DISPLAY_FOUND_NONE_FOR_LANG_ERR Terminology_TX_Display_Wrong

Error validating coding Codes & terminology

What it means: The terminology check failed with an error (see the detail).
Why: The code could not be confirmed as valid.
How to fix: Check system URL, code and version for typos.

Validator message IDs: Terminology_PassThrough_TX_Message Terminology_TX_Error_CodeableConcept Terminology_TX_Error_CodeableConcept_Max Terminology_TX_Error_Coding1 Terminology_TX_Error_Coding2

Invalid Coding.system Codes & terminology

What it means: system must be an absolute URI of a code system, not a relative path or a ValueSet URL.
Why: System URIs are the global names of vocabularies.
How to fix: Use the full code system URL, for example http://loinc.org or http://snomed.info/sct.

Validator message IDs: Terminology_TX_System_Invalid Terminology_TX_System_Relative Terminology_TX_System_ValueSet Terminology_TX_System_ValueSet2

Supplement used as a system Codes & terminology

What it means: Code system supplements cannot be used in Coding.system.
Why: Supplements only add information.
How to fix: Use the base code system URL.

Validator message IDs: CODESYSTEM_CS_NO_SUPPLEMENT

Unknown code or code system Codes & terminology

What it means: The code system URL or the code is not known to the validator.
Why: A wrong system URL makes the code meaningless to receivers.
How to fix: Check the system URL character by character (no trailing slash or typo) and that the code exists in that system. Use the NP Core code system URLs from the IG.

{ "system": "http://loinc.org", "code": "8302-2", "display": "Body height" }

Validator message IDs: Terminology_TX_System_Unknown Unknown_Code_in Unknown_Code_in_Version Unknown_Code_in_Version_SCT

Value set not found Codes & terminology

What it means: The value set referenced by the profile or resource is not available.
Why: The binding cannot be checked.
How to fix: If this is in your own resource, check the URL. If it is in a profile, report it to the sandbox team.

Validator message IDs: Reference__refers_to_a__not_a_ValueSet Terminology_TX_ValueSet_NotFound Terminology_TX_ValueSet_NotFound_CS Unable_to_resolve_value_Set_

Wrong number of codings Codes & terminology

What it means: The number of codings differs from what the profile requires.
Why: The profile fixes the coding list.
How to fix: Provide exactly the codings the profile requires.

Validator message IDs: Terminology_TX_Binding_Missing3 Terminology_TX_Coding_Count