Diagnostic codes

Every diagnostic SJON reports carries a code, and every one of the 130 codes has a page here. The codes are wire-stable: they are appended, never renamed and never reordered, so a code you match on today keeps meaning the same thing in the next release. That is what makes matching on one in your own tooling a reasonable thing to do.

You will meet these three ways round. Your editor’s language server attaches one to a squiggle, with a codeDescription.href pointing at the page below. The command line prints one as a help: link under the caret. And sjon explain <code> prints the same text in your terminal, without a browser.

The list is in catalogue order, which is the declaration order of the wire-stable enum. That is not alphabetical on purpose: codes were appended in related batches, so the neighbours of the one you came here for are usually the ones you are about to hit next.

• unspecifiedGeneric catch-all when no more-specific code applies.
• unknown_formA form's head name is not declared by any loaded plugin.
• unknown_keyForm does not declare this :keyword and is not :open true.
• ambiguous_formTwo plugins declare a form with the same bare head; qualify the spelling.
• ambiguous_exprTwo plugins declare an expression with the same name; qualify the spelling.
• ambiguous_element_kindElement kind reference matches multiple plugin-declared kinds.
• unknown_element_kindElement kind name resolves to no plugin.
• recursion_depthValidator's depth ceiling exceeded; the input is pathologically nested.
• not_cross_refSymbol is not a registered name for the cross-ref's target: no target instance declares (or provides) it.
• duplicate_cross_ref_targetTwo forms share the same :name value within one cross-ref's target scope.
• unknown_cross_ref_targetThe :target declared on a (cross-ref …) resolves to no form in the aggregated schema.
• ambiguous_cross_ref_targetCross-ref symbol matches multiple targets, typically a name collision under scopes.
• cross_ref_name_key_unknownThe :name-key declared on a (cross-ref …) is not a key on the target form.
• acyclic_without_self_edge(cross-ref … :acyclic true) declared on a kind that can't form cycles.
• cyclic_cross_refAcyclic cross-ref forms a cycle; at least one edge must be removed.
• unknown_cross_ref_scopeCross-ref :scope is not a known form name.
• ambiguous_cross_ref_scopeCross-ref :scope matches multiple form names; qualify the spelling.
• cross_ref_outside_scopeCross-ref references a target outside the enclosing scope's instance.
• duplicate_keySame :key appears twice on the same form.
• too_many_keysForm has more keyword slots than Plugin.MAX_FORM_KEYS permits.
• missing_required_keyForm omits a :key :optional false slot with no default.
• positional_not_allowedForm's :positional declaration is none but a positional child was provided.
• expr_kvpair_not_allowedExpression function does not opt into labeled-call form (:param-names).
• missing_discriminant_keyDiscriminated form lacks the discriminant key.
• unknown_discriminant_valueDiscriminant's value is not a member of its declared enum.
• discriminant_not_closed_enumDiscriminant key's value-kind does not declare a closed (member-set …).
• variant_key_collisionVariant declares a key that already lives on the form's common keys.
• mutually_exclusive_keys_presentMultiple alternatives of an exclusive group are present at once.
• multiple_defaulted_alternatives_in_groupExclusive group has more than one alternative with a :default.
• required_one_of_missingexactly-one exclusive group has zero alternatives present.
• exclusive_group_invalidExclusive group declaration is malformed (overlapping alts, missing keys, …).
• wrong_underlyingValue's structural shape does not match the declared :underlying.
• vector_length_mismatchVector value does not match the declared :vector :len.
• unit_requiredNumber value lacks a unit but the kind requires one.
• unit_not_allowedNumber value carries a unit but the kind's :allowed list rejects it.
• not_memberClosed (member-set …) does not include this value.
• deprecated_memberMember is declared :deprecated true: accepted, but the LSP marks it deprecated.
• not_head_memberForm's head is not in the kind's (head-set …) whitelist.
• union_no_branch_matchedNo alternative in a (union-shape …) accepted the value.
• nested_unionUnion alternative resolves to another union; flatten the alternatives.
• arity_mismatchExpression function called with the wrong number of arguments.
• expr_type_mismatchExpression argument's type does not satisfy the function's :params declaration.
• expr_unknown_labelLabeled-call kvpair key does not match any declared :param-names.
• expr_duplicate_labelLabeled call supplies the same label twice.
• expr_missing_labelLabeled call omits a declared parameter.
• expr_mixed_argsCall mixes positional and labeled arguments; pick one form.
• invalid_manifestManifest source failed to load (read error, malformed shape, etc.).
• unresolved_pluginA (use-plugin …) reference's name is not in the project file.
• plugin_version_mismatch(use-plugin … :version …) pin disagrees with the manifest's :version.
• plugin_hash_mismatch(use-plugin … :hash …) pin does not match the resolved wasm bytes.
• duplicate_plugin_nameTwo manifests in the project's :plugins index declare the same :name.
• plugin_name_mismatchResolved manifest's :name differs from the (use-plugin …) name.
• project_file_not_foundsjon-project.sjon not found at the requested or discovered root.
• plugin_abi_mismatchPlugin wasm reports a sjon_plugin_abi_version() the host does not implement.
• plugin_export_missingManifest references a :impl wasm:<name> export the wasm binary does not define.
• plugin_import_forbiddenPlugin wasm imports a forbidden host symbol; ABI v2 plugins are pure.
• plugin_wasm_requiredManifest declares :impl wasm:… but the resolver returned no wasm bytes.
• plugin_describe_invalidsjon_plugin_describe() output is malformed or inconsistent with the manifest.
• plugin_func_trappedPlugin export trapped during invocation (unreachable, OOB memory, etc.).
• plugin_func_result_typePlugin export's return value's tag mismatches the manifest's declared :result.
• plugin_func_failedPlugin export returned an error status: a runtime semantic failure.
• plugin_func_alloc_failedPlugin allocation hook (sjon_alloc) returned null.
• default_eval_failedExpression-shaped :default failed at evaluation time.
• lowering_hook_missingHost has no implementation registered for the :lowering :hook named by the manifest.
• lowering_hook_failedLowering hook returned an error or invalid output.
• lowering_produced_invalid_headLowering output's form head is not in the manifest's :produces whitelist.
• lowering_produced_lowerable_headLowering output's form head is itself a surface; lowering must terminate.
• lowering_output_too_largeLowering output exceeded one of MAX_LOWERED_FORMS / MAX_LOWERED_DEPTH / MAX_LOWERED_BYTES.
• number_overflow_exact_integerInteger literal exceeds u64; falls back to f64 with precision loss.
• date_invalid_yearDate year 0000 rejected (ISO 8601 disallows year 0).
• date_invalid_monthDate month outside [1, 12].
• date_invalid_dayDate day outside the month's valid range.
• time_invalid_hourTime hour outside [0, 23].
• time_invalid_minuteTime minute outside [0, 59].
• time_invalid_secondTime second outside [0, 59] (no leap seconds).
• number_below_minNumber value below inclusive :min.
• number_above_maxNumber value above inclusive :max.
• number_at_or_below_exclusive_minNumber value ≤ :min when :exclusive-min true.
• number_at_or_above_exclusive_maxNumber value ≥ :max when :exclusive-max true.
• number_not_integerValue violates :integer true (fractional or non-finite).
• numeric_bound_unit_mismatchBound carries a unit but the validated value does not match it.
• numeric_bounds_invalid(numeric-bounds …) declaration is internally inconsistent.
• string_too_shortString shorter than :min-len UTF-8 codepoints.
• string_too_longString longer than :max-len UTF-8 codepoints.
• string_format_mismatchString value fails the declared :format (email/uri/path/uuid/semver).
• string_pattern_mismatchString value fails the declared :pattern (regex).
• string_pattern_unsupportedHost build has no regex engine; the :pattern is stored but not checked.
• string_bounds_invalid(string-bounds …) declaration is internally inconsistent.
• exclusive_bundle_partialMulti-key bundle in an exclusive group is partially present.
• exclusive_bundle_collisionSame key appears in two alternatives of the same exclusive group.
• plugin_wasm_resolved_outside_packageManifest's :wasm-file resolves outside its own directory.
• plugin_wasm_self_hash_malformed:wasm-sha256 is not in the canonical sha256-<64 lowercase hex> shape.
• plugin_wasm_self_hash_mismatchManifest's :wasm-sha256 stamp disagrees with the bytes on disk.
• license_unrecognizedAdvisory: :license is not a canonical SPDX identifier.
• too_many_keywordsAdvisory: :keywords exceeds the soft cap of 16 entries.
• sjon_format_unsupportedRetired: manifests no longer declare a format version; this code is never emitted.
• unknown_project_keyAdvisory: project file declared a top-level key the host doesn't recognize.
• glob_no_matchesAdvisory: a :documents pattern matched zero files.
• pin_disagreementProject (plugin-entry … :version/:hash) pin disagrees with a (use-plugin …) pin.
• project_documents_outside_root:documents glob resolves outside the project root.
• lockfile_driftLockfile entry's hash disagrees with the on-disk bytes.
• lockfile_missing_entryProject references a plugin the lockfile does not record.
• lockfile_orphanAdvisory: lockfile entry is no longer referenced by the project.
• lockfile_version_unsupportedLockfile :version exceeds this host's understanding.
• lockfile_corruptLockfile failed to parse or has the wrong top-level shape.
• not_flag_memberPositional keyword flag is not in the form's :positional (flag-set …) set.
• lowering_cycleA :lowering :produces graph cycles: following produces-edges leads back to a lowering form.
• lowering_target_plugin_absentA :lowering :produces head names a plugin that isn't loaded: a dangling cross-plugin edge.
• duplicate_positional_flagA declared positional keyword flag is repeated on one form, e.g. (task :done :done).
• lowering_nested_lowerableA :lowering form is a positional child of another :lowering form; container and child can't both lower.
• unit_forbiddenNumber value carries a unit but the kind's :unit (unit-shape :reject true) demands bare numbers.
• vector_too_shortVector has fewer elements than the declared :vector :min-len.
• vector_too_longVector has more elements than the declared :vector :max-len.
• vector_bounds_invalid(vector-shape …) declaration is internally inconsistent (:len with a range, or :min-len > :max-len).
• repr_out_of_rangeNumber value does not fit its value-kind's :repr GPU type (out of range, or non-integral under u16/u32/i32).
• unknown_local_formForm head in a slot-local slot matches neither a local form nor any global form.
• pattern_tick_overflowA fast / slow combinator expanded the query window past the 2^53 tick ceiling.
• pattern_value_eval_failedA (pure …) expression leaf failed to evaluate at the cycle-0 dry-run.
• pattern_value_result_invalidA (pure …) expression evaluated but produced a value no hap can carry.
• unknown_cross_ref_providerCross-ref :provider names an extractor no loaded plugin declares.
• ambiguous_cross_ref_providerBare cross-ref :provider name is declared by two or more plugins; qualify the spelling.
• cross_ref_source_key_unknownThe :source-key declared on a provider-route (cross-ref …) is not a string-typed key on the target form.
• cross_ref_extraction_failedA cross-ref provider ran against this source and rejected it, so the set of valid names here is unknown.
• cross_ref_provider_unavailableThe provider backing this cross-ref could not be run, so the set of valid names here is unknown.
• cross_ref_target_collapseTwo value-kinds cross-reference the same form but disagree on how its member set is built; the first one declared wins.
• number_not_multipleValue is not an exact multiple of :multiple-of.
• dependent_key_missingA key that is present requires sibling keys that are absent.
• union_ambiguousA name is registered by two cross-ref alternatives of one union, so declaration order decides which.
• positional_too_manyMore positional children than a (head-set …) ceiling allows: the head's :max, or the set's :max-children.
• positional_missingFewer positional children than a (head-set …) floor requires: the head's :min, or the set's :min-children.