Diagnostic reference

citry.parse.syntax

Invalid template syntax. The Citry parser could not parse the template at the reported source range.

When this appears: Citry encounters malformed template markup, an incomplete expression, or another template grammar error.

Default severity: error.

<section>
  <p>Hello</p>

Reported by: template parser APIs, citry format, citry check, citry-lsp.

citry.parse.value

Invalid template value. The parser received a template value that cannot be represented by Citry's template model.

When this appears: A parser API receives a value that it cannot convert into Citry template source or a supported template value.

Default severity: error.

Reported by: template parser APIs, citry format, citry check, citry-lsp.

citry.parse.configuration

Template parser configuration failed. Project-specific parser configuration could not be constructed or applied.

When this appears: Citry cannot build the parser rules required by the selected application or component registry.

Default severity: error.

Reported by: citry check, citry-lsp.

citry.template.unknown-variable

Unknown template variable. A parser-proven root variable is not declared by every component that consumes the template.

When this appears: A name used in an interpolation or Python-valued template attribute is absent from the proven template data, configured globals, and lint-only variables.

Default severity: error. The application can configure this severity.

Messages:

• Closed template data:

  Template variable '{name}' is not available in this template.

• Template data allows extra names:

  Template variable '{name}' is not declared. It may be supplied dynamically.

• Template data could not be inspected:

  Template variable '{name}' is not declared. Citry could not determine whether it is supplied dynamically.

<p>{{ missing_name }}</p>

<div c-title="missing_name"></div>

Reported by: citry check, citry-lsp.

citry.template.unknown-component

Unknown component. A component tag is not registered in the selected Citry registry.

When this appears: A template uses a component tag whose name is absent from the selected application or library registry.

Default severity: error.

Message:

Component <{tag}> is not registered.

<c-missing-card />

Reported by: citry check, citry-lsp.

citry.js-data.unsupported-type

JsData field is not a JSON type. A declared or inferred JsData value cannot be represented safely by Citry's JSON wire format.

When this appears: A JsData field has a type that strict JSON serialization cannot carry, such as bytes, a set, a callable, or a date/time object without an explicit conversion.

Default severity: warning.

Message:

JsData field '{name}' is not a clean JSON value: {detail}. Browser tooling will treat its type as unknown.

class Card(Component):
    class JsData:
        selected_ids: set[int]

Reported by: citry check, citry-lsp.

citry.alpine.unknown-variable

Unknown Alpine variable. A free identifier in an Alpine expression is absent from the component's proven browser scope.

When this appears: An Alpine expression references a root that is not supplied by JsData, x-data, an enclosing x-for, a proven $component scope write, an Alpine or Citry magic, a browser global, or configured lint-only Alpine variables.

Default severity: error. The application can configure this severity.

Message:

Alpine variable '{name}' is not available in this component.

<button :disabled="submitting1">Save</button>

Reported by: citry check, citry-lsp.

citry.csp.incompatible-browser-code

Browser code is incompatible with strict CSP. An Alpine or Citry browser expression uses a host or source form unsupported by the pinned Alpine CSP evaluator.

When this appears: The selected Citry application configures CSP warning or strict mode and a source-classifiable browser expression is incompatible with Alpine CSP 3.16.1.

Default severity: error. The application can configure this severity.

Message:

Alpine CSP 3.16.1 cannot evaluate {detail} here. Move complex logic to Component.js and call a scope method from the template.

<button @click="items.map(item => item.id)">Save</button>

Reported by: citry check, citry-lsp.

citry.component-js.unknown-variable

Unknown component JavaScript variable. A free identifier inside a $component initializer is absent from its lexical scope and configured globals.

When this appears: A $component initializer references a name that was not declared locally, destructured from the callback context, supplied by the JavaScript or browser environment, or configured as a lint-only component JavaScript global.

Default severity: error. The application can configure this severity.

Message:

Component JavaScript variable '{name}' is not defined.

$component(({ data }) => {
  scope.ready = data.ready;
});

Reported by: citry check, citry-lsp.

citry.browser.unknown-server-event

Unknown server event. A literal browser event reference names no effective handler on the component that owns it.

When this appears: An Alpine expression or component JavaScript calls sendEvent, $sendEvent, $loading, or $error with an unknown non-empty string literal, or a declarative @c-* binding names an unknown handler.

Default severity: error.

Message:

Server event '{name}' is not declared by this component.

<button @click="sendEvent('missing')">Run</button>

<button @c-click="missing">Run</button>

<span x-show="$loading('missing')">Saving</span>

Reported by: citry check, citry-lsp.

citry.browser.unknown-component-prop

Unknown client prop. A static $c-props object contains a key that the child component does not declare.

When this appears: A statically resolved component receives a direct $c-props object key absent from its static $component({props}) declaration.

Default severity: error.

Message:

Client prop '{name}' is not declared by <{tag}>.

<c-card $c-props="{ missing: value }" />

Reported by: citry check, citry-lsp.

citry.browser.missing-component-prop

Missing required client prop. A static $c-props object omits a required prop declared by the child component.

When this appears: A statically resolved component receives a direct $c-props object without a required static $component({props}) key and no dynamic spread can supply it.

Default severity: error.

Message:

Required client prop '{name}' is missing for <{tag}>.

<c-card $c-props="{}" />

Reported by: citry check, citry-lsp.

citry.browser.incompatible-component-prop

Incompatible client prop. A static $c-props value has a proven type outside the child component's prop declaration.

When this appears: Citry can prove both the authored value type and the static $component({props}) type, and the value cannot satisfy that prop.

Default severity: error.

Message:

Client prop '{name}' expects {expected}, but this value is {actual}.

<c-card $c-props="{ count: 'many' }" />

Reported by: citry check, citry-lsp.

citry.check.template-declaration

Template declaration unavailable. The checker could not safely inspect or identify a component's template declaration.

When this appears: The selected component's template or template_file declaration raises during inspection or cannot be identified safely.

Default severity: error.

Message:

Citry could not inspect this component's template declaration: {detail}

Reported by: citry check.

citry.check.template-language-unsupported

Unsupported template language. The checker only analyzes native Citry templates and skipped a declaration with another language.

When this appears: A component sets template_lang to a non-None value; citry check currently analyzes only native Citry templates.

Default severity: error.

Message:

Citry cannot check template_lang with a {type} value. This template was skipped.

Reported by: citry check.

citry.check.template-value-invalid

Invalid template declaration value. A template or template_file declaration has a value type the checker cannot use.

When this appears: Component.template is not a string, or Component.template_file is neither a string nor a pathlib.Path.

Default severity: error.

Messages:

• Inline template:

  Component.template must be a string. This template was skipped.

• Template file:

  Component.template_file must be a string or Path. This template was skipped.

class Card(Component):
    template = build_template()

Reported by: citry check.

citry.check.template-file-not-found

Template file not found. No template file exists at any location resolved from template_file.

When this appears: Component.template_file points to a path that does not exist in the component directory or any configured template directory.

Default severity: error.

Message:

Template file '{path}' was not found. Searched: {locations}.

class Card(Component):
    template_file = "missing.html"

Reported by: citry check.

citry.check.template-file-unreadable

Template file could not be read. The resolved template file could not be opened or decoded as UTF-8.

When this appears: Citry resolves Component.template_file but cannot open the file or decode it as UTF-8.

Default severity: error.

Message:

Citry could not read this template file: {detail}

Reported by: citry check.

citry.check.template-namespace-unavailable

Template variables unavailable. The checker could not determine the variables supplied to a component template.

When this appears: citry check cannot inspect the component's declared or inferred template data namespace.

Default severity: error.

Message:

Citry could not inspect this template's variables: {detail}

Reported by: citry check.

citry.check.python-source-unreadable

Python source could not be analyzed. Static checking could not read, decode, or parse a Python source file.

When this appears: Static discovery reaches a Python file that cannot be read, decoded, or parsed.

Default severity: error.

Message:

Citry could not analyze this Python source: {detail}

Reported by: citry check.

citry.i18n.catalog-invalid

Invalid Fluent catalog source. A Fluent source unit failed Citry's production parser or i18n contract checks.

When this appears: A messages block or catalog file contains invalid Fluent syntax, an unsupported parameter type, or another source-level i18n error.

Default severity: error.

Reported by: citry check, citry-lsp.

citry.i18n.unknown-message

Unknown i18n message. A literal translation key is absent from the checked project catalog.

When this appears: A direct tr() call, <c-trans> tag, $c-tr binding, or bounded browser bind() call names a message value or attribute that no component or configured catalog package defines.

Default severity: error.

Reported by: citry check, citry-lsp.

citry.i18n.argument-invalid

Invalid i18n argument. A translation binding, formatter, parser, or rich-message call does not match its checked contract.

When this appears: A literal i18n call or $c-tr binding is malformed, has missing, unknown, or mistyped message inputs, uses an unknown named profile, or supplies the wrong <c-trans> values or fills.

Default severity: error.

Reported by: citry check, citry-lsp.

citry.i18n.cross-language-fallback

Cross-language i18n fallback. A plain translated string falls back to a different language without a place to carry that language metadata.

When this appears: A text-only translation can select a source or fallback locale whose canonical language tag differs from the requested locale.

Default severity: error.

Reported by: citry check.

citry.i18n.client-message-invalid

Invalid client i18n message. A message declared for browser use is missing or lacks complete locale coverage.

When this appears: Component.I18n.client_messages names an unknown output or an output that would fall back across languages in a client-enabled subtree.

Default severity: error.

Reported by: citry check.

citry.format.syntax

Invalid template syntax. Formatting stopped because the template does not parse.

When this appears: A format command receives a template with a Citry syntax error.

Default severity: error.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.suppression

Invalid formatter directive. A fmt directive is unmatched or appears in a context where its requested scope is invalid.

When this appears: A fmt:on, fmt:off, or fmt:skip directive has no valid matching scope at its authored position.

Default severity: error.

{# fmt: on #}
<div></div>

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.invariant

Formatter safety check failed. The formatter refused to write output after an internal span, structure, or idempotence check failed.

When this appears: Formatting output fails one of Citry's safety checks, so Citry refuses to apply the edit.

Default severity: error.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.unsupported

Formatting shape unsupported. The formatter conservatively declined a valid template shape it cannot yet rewrite safely.

When this appears: The template is valid, but its source shape is outside the formatter's currently supported rewrite rules.

Default severity: error.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.provider-invalid

Embedded formatter returned invalid output. A JavaScript or CSS formatter response failed Citry's source-bound validation.

When this appears: A delegated JavaScript or CSS formatter returns an edit that does not match the requested embedded region.

Default severity: error.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.embedded-suppressed

Embedded formatting suppressed. A fmt directive deliberately prevented formatting of a JavaScript or CSS region.

When this appears: A fmt:off or fmt:skip directive covers an embedded JavaScript or CSS region.

Default severity: information.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.embedded-language-unsupported

Embedded language unsupported. Citry recognized an embedded region but cannot delegate its declared language.

When this appears: An embedded script or style region declares a language for which Citry has no formatter provider.

Default severity: warning.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.embedded-interpolation-unsupported

Embedded interpolation unsupported. A JavaScript or CSS region contains Citry interpolation that cannot be safely delegated yet.

When this appears: An embedded JavaScript or CSS region contains Citry interpolation, which cannot yet be mapped safely through an external formatter.

Default severity: warning.

<script>
  const title = "{{ title }}";
</script>

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.provider-unavailable

Embedded formatter unavailable. No JavaScript or CSS formatter returned a usable result for a delegated region.

When this appears: Citry asks the editor to format embedded JavaScript or CSS, but no installed provider returns an edit.

Default severity: warning.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.host-syntax

Invalid Python host syntax. A Python file containing component assets could not be parsed before formatting.

When this appears: A format command targets a Python file whose current source has invalid Python syntax.

Default severity: error.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.ineligible

Document is not eligible for formatting. The selected document, position, or asset is outside Citry's proven formatting scope.

When this appears: Citry cannot prove that the selected document or cursor position belongs to a supported Citry template, script, or style region.

Default severity: error.

Reported by: citry format, citry-lsp, the Citry VS Code extension.

citry.format.stale-document

Document changed during formatting. Formatting was discarded because its source-bound plan no longer matches the current document.

When this appears: The document changes after Citry prepares a format plan but before the editor can apply it.

Default severity: error.

Reported by: citry-lsp, the Citry VS Code extension.

citry.format.cancelled

Formatting cancelled. The editor cancelled a formatting operation before Citry could apply it.

When this appears: The editor or user cancels a format request before Citry applies its edits.

Default severity: information.

Reported by: the Citry VS Code extension.

citry.python.*

Provider: ty. Python semantic diagnostics retained from the pinned ty analyzer. The suffix and message remain provider-owned.