Understanding diagnostics
Start with the operation that failed: loading a source, compiling its relationships, validating its dialect, emitting an artifact, or executing a consumer operation. Success at one step does not imply success at all the others.
Read the location and relationship
A diagnostic supplies a code, message, and source location. Some also identify related locations, such as a conflicting declaration or contributing rule. Use those locations to inspect both ends of the relationship before changing the model.
For example, “Unresolved reference Currency” inside Notebook can mean that
Currency belongs to the enclosing Shop, where the intended path is
@Shop.Currency. It does not necessarily mean that the property is absent.
Common failures
| Symptom | What to inspect |
|---|---|
| Expected punctuation or unterminated text | Closing braces, property semicolons, quotes, and caret escapes |
| Duplicate root/member/entry | Effective identity within its scope; target selection may have retained two alternatives |
| Unresolved reference | Scope, qualified path, imported root, effective entry name, and whether the target survived filtering |
| Unresolved composition target | Contributor's accessible definition path and selection |
| Unexpected inherited value | Contributor order, local override, inherited-reference rebinding, and array entry identity |
| Missing child properties after composition | A same-named child was replaced as a unit; compose that child explicitly to retain its base |
| Dependency or composition cycle | The chain of files or contributors points back into itself |
| Scalar dependency cycle | Values depend on each other without a terminating value |
| Dialect rejection | The permitted kind/property, source form, resolved category, or scalar constraint |
| JSON recursive projection | The source graph compiled, but its reference projection would recursively expand |
| Unresolved external value | Selected target name/case or the consumer's read handler |
| Included data missing from references | Include contributes output; use module to establish reference access |
| Imported data missing from output | Module-only definitions do not contribute independently; include them if intended |
Diagnostic families
| Family | Area |
|---|---|
NXS1xxx |
Tokenization, including quoted text and escapes |
NXS2xxx |
Source/dependency syntax |
NXS3xxx |
Declaration identity and target-clause errors |
NXS4xxx |
Composition |
NXS5xxx |
Internal value/reference resolution |
NSV1xxx |
Invalid language-definition rules |
NSV2xxx |
Invalid subject structure or values |
NSV3xxx |
Reference constraints |
File loading, source-provider, Live, artifact, and consumer diagnostics also carry their own messages. Preserve the actual message and location rather than classifying every failure as a syntax error.
Reduce a failing model
Keep the entry file, the necessary imported definitions, and the actual target selection. Remove unrelated contributions while retaining the relationship that fails. Inspect an effective value through JSON when materialized output is suitable, or through Live when the model depends on external values or real reference links.
The editor can show diagnostics, navigate references, and help locate declarations. Those services use the language compiler's model; the language-server guide describes their configuration.