GitHub v1.3.1

Diagnostics

Reference

Every code Coralite can emit, grouped by domain, with its severity, whether coralite fix can repair it, and how to resolve it.

Codes are contracts. They are stable across releases, safe to match in CI, and the same strings appear in coralite check, the JSON report and this page. Filter a run with --code E201, silence a single finding with a pragma, or hand the JSON to an agent.

Working with diagnostics

bash
Code copied!
# Audit the workspace
coralite check

# Only the codes you are cleaning up right now
coralite check --code E201 E202 --only-failed

# Machine-readable report for CI or an agent
coralite check --format json

# Preview and apply automatic repairs
coralite fix --dry-run
coralite fix --code E201

Every code carries a severity. Errors fail the build; warnings are reported and only fail under --strict. Auto-fixable codes name the AST transformation coralite fix applies, so a repair is deterministic rather than a suggestion.

Component diagnostics can be silenced locally with a pragma comment inside the component file. Config, route and stylesheet errors abort the build and cannot be ignored.

html
Code copied!
<template id="ui-legacy-card">
  <!-- coralite-ignore W402 -->
  <div ref="shell">{{ title }}</div>
</template>

The catalogue from the CLI

The same catalogue that renders this page ships with the framework, so you can query it without leaving the terminal or pull it into tooling:

bash
Code copied!
coralite diagnostics
coralite diagnostics --family plugin --fixable
coralite diagnostics --search template --format json
52codes
41errors
11warnings
12auto-fixable

Component 24

Component diagnostics
Code Severity Diagnostic
CORALITE-E101 error
Blocked attribute type

An attribute declares Array or Object as its type.

Fix. Use String, Number or Boolean and pass structured data through server() and state.

CORALITE-E102 errorauto-fix
Attribute declares required and default

An attribute sets required: true and also declares a default value.

Fix. Keep required for mandatory attributes, or keep default and drop required.

Auto-fix. strip_default

coralite fix --code E102

CORALITE-E103 error
Asynchronous attribute handler

An attribute transform or validate function is asynchronous.

Fix. Make attribute coercion synchronous; fetch asynchronous data in server().

CORALITE-E104 error
Reserved context key collision

A state property or context key collides with a framework-reserved name.

Fix. Rename the property so it does not shadow state, refs, signal, emit, root or observe.

CORALITE-E105 errorauto-fix
Invalid context shape

A getter, style or slots handler uses the wrong parameter shape, context.attributes, or legacy arguments.

Fix. Destructure ({ state }) or take the context object and read context.state.

Auto-fix. rewrite_context_attributes, rewrite_getter_context, style_context_migration, slots_context_migration

coralite fix --code E105

CORALITE-E106 errorauto-fix
Invalid provide or consume option

provide must be an object or Map, and consume must use a supported shape.

Fix. Declare provide as an object or new Map(), and consume as an array or keyed object.

Auto-fix. convert_to_object, convert_to_array

coralite fix --code E106

CORALITE-E107 error
Invalid option or unknown block

A component option has the wrong value, or a plugin declares an unknown block.

Fix. Use a boolean for formAssociated/formControl, a valid listStrategy, and only documented plugin blocks.

CORALITE-E109 error
CSS import outside client()

A .css file is imported at module scope, outside client(), or with unsupported options.

Fix. Load stylesheets inside client() with await import('pkg/styles.css', options).

CORALITE-E201 errorauto-fix
Complex template expression

A template token contains an expression instead of a flat identifier.

Fix. Move the expression into a synchronous getter and reference the getter name.

Auto-fix. lift_to_getter

coralite fix --code E201

CORALITE-E202 errorauto-fix
Missing template ref

client() calls refs() for a name that no template element declares.

Fix. Add ref="name" to the element, or call the ref that exists.

Auto-fix. inject_ref

coralite fix --code E202

CORALITE-E203 errorauto-fix
Inline event handler

A template element uses an inline on* attribute, which violates the CSP contract.

Fix. Add a ref and bind the listener in client() with { signal }.

Auto-fix. remove_attribute

coralite fix --code E203

CORALITE-E204 error
Missing or invalid template id

The <template> has no id, or the id is not a valid custom element name.

Fix. Give the template a hyphenated id such as <template id="ui-card">.

CORALITE-E205 error
Unresolved template token

A {{ token }} does not resolve to an attribute, state property or getter.

Fix. Declare the symbol in attributes, server() state, or getters, and check spelling.

CORALITE-E301 errorauto-fix
Module-scope import in client()

client() references a variable bound by a static top-level import.

Fix. Use await import() inside client() so the module is not serialized by reference.

Auto-fix. dynamic_import

coralite fix --code E301

CORALITE-E302 warning
State mutated in observe()

An observe() callback assigns reactive state, which can loop indefinitely.

Fix. Mutate state in event handlers; use observe() only for external side effects.

CORALITE-E303 error
Asynchronous style getter

A style function is async.

Fix. Style functions must be synchronous; derive the value from state instead.

CORALITE-E304 error
Node global in client()

client() references a Node-only runtime global such as process or Buffer.

Fix. Use browser APIs, or fetch build-time data in server() and pass it through state.

CORALITE-E401 warning
HTTP request global in server()

server() references request or response identifiers that Coralite does not provide.

Fix. Read route params and configuration from the context instead of HTTP globals.

CORALITE-E403 error
Unresolvable stylesheet

A dynamic .css import points to a file or package that cannot be resolved.

Fix. Check the relative path or package name, and confirm the file exists on disk.

CORALITE-W204 warningauto-fix
Redundant ref existence guard

client() checks whether a template ref exists, but refs are guaranteed at mount.

Fix. Use the ref directly and bind with { signal } for lifecycle cleanup.

Auto-fix. unwrap_ref_guard

coralite fix --code W204

CORALITE-W401 warning
Unused declaration

A getter, server state property or attribute declaration is never used.

Fix. Remove the declaration or reference it from the template or a handler.

CORALITE-W402 warningauto-fix
Unused template ref

An element declares ref="name" but no handler reads it.

Fix. Remove the ref, or add the coralite-ignore pragma while wiring it up in a later step.

Auto-fix. remove_unused_ref

coralite fix --code W402

CORALITE-W501 warning
Reserved tag prefix

A component tag uses a reserved prefix such as coralite-, c- or router-.

Fix. Use a project prefix such as site-, ui- or app-.

CORALITE-W601 error
Defensive guard on framework context

Code guards a context key or global that the framework guarantees, hiding real errors.

Fix. Remove the guard; if the value is missing the bug is in configuration or the build.

Plugin 17

Plugin diagnostics
Code Severity Diagnostic
CORALITE-E407 error
Invalid plugin paths() result

A plugin onPageSet hook returned a paths value that is not an array.

Fix. Return an array of parameter objects from onPageSet, or omit paths.

CORALITE-P101 error
Missing plugin name

definePlugin() has no name, or the name is not a non-empty string.

Fix. Add a unique, non-empty name to the plugin definition.

CORALITE-P102 error
Reserved plugin name

The plugin name collides with a core plugin or a reserved runtime key.

Fix. Rename the plugin so it does not shadow metadata, refs, testing or another core key.

CORALITE-P201 errorauto-fix
Single-phase context resolver

server.context or client.context returns an object instead of a resolver function.

Fix. Return (instanceContext) => ({ ... }) from the first phase.

Auto-fix. wrap_two_phase_context

coralite fix --code P201

CORALITE-P202 error
Invalid server hook or property

The server block declares an unknown property or a hook that is not a function.

Fix. Use a documented hook name and give it a function value.

CORALITE-P203 error
Server-only import in client block

A client block imports a Node-only module such as node:fs.

Fix. Move the import into the server block or load it dynamically where it is valid.

CORALITE-P204 error
Invalid modes declaration

The plugin modes property is not a non-empty array of known mode names.

Fix. Declare modes as an array such as ['development', 'production'].

CORALITE-P205 error
Invalid dependencies declaration

The dependencies property is not an array of plugin names.

Fix. List plugin names as an array of non-empty strings.

CORALITE-P206 error
Invalid plugin config schema

A plugin config declaration uses an unsupported type, or still uses depends.

Fix. Use String, Number, Boolean, Object or Array, and rename depends to dependencies.

CORALITE-P207 error
Invalid plugin config value

A call-time config value is unknown, missing when required, or the wrong type.

Fix. Pass only declared keys with values that match the declared schema.

CORALITE-P209 error
Reassigned config.clientConfig

The plugin config proxy forbids replacing clientConfig as a whole.

Fix. Write to config.clientConfig.<key> instead of assigning the object.

CORALITE-P210 error
Non-serializable client config

client.config contains functions, circular references or other non-JSON values.

Fix. Keep client.config to plain serializable data and move behaviour into hooks.

CORALITE-P211 error
Mixed context declarations

A plugin declares top-level context together with server.context or client.context.

Fix. Use top-level context for ambient helpers, or environment-specific context, never both.

CORALITE-P301 error
Outer scope leak in client code

A serialized plugin client function references a module-scope variable.

Fix. Move the value into client.config or resolve it inside the function.

CORALITE-P302 error
Function-valued client.config

client.config is declared as a function instead of a serializable object.

Fix. Declare client.config as a plain object of serializable values.

CORALITE-P303 error
Invalid client hook or property

The client block declares an unknown property or a deprecated hook.

Fix. Use documented client hooks such as onBeforeComponentRender, and give them functions.

CORALITE-P401 errorauto-fix
Missing definePlugin wrapper

The plugin exports a bare object instead of calling definePlugin().

Fix. Wrap the configuration in export default definePlugin({ ... }).

Auto-fix. wrap_define_plugin

coralite fix --code P401

Page 4

Page diagnostics
Code Severity Diagnostic
CORALITE-E402 error
Invalid page paths() result

A page paths() block returned something other than an array of parameter objects.

Fix. Return an array whose entries provide every declared route parameter.

CORALITE-PAGE-101 warning
Unknown custom element

A page uses a custom element tag that no component defines.

Fix. Register the component, fix the tag spelling, or remove the element.

CORALITE-PAGE-102 errorauto-fix
Missing required attribute

A page tag omits an attribute the component marks as required.

Fix. Add the attribute with a valid value, or relax required in the component schema.

Auto-fix. add_required_attribute

coralite fix --code PAGE-102

CORALITE-PAGE-201 error
Page reaches into component internals

A page script queries or mutates DOM inside a custom element instance.

Fix. Communicate through attributes, events or context instead of internal nodes.

Accessibility 4

Accessibility diagnostics
Code Severity Diagnostic
CORALITE-A101 warning
Image missing alt text

A template <img> has no alt attribute.

Fix. Add a descriptive alt, or alt="" when the image is decorative.

CORALITE-A102 warning
Link without accessible text

An <a> element has no text content and no aria-label.

Fix. Add visible text, or an aria-label that describes the destination.

CORALITE-A103 warning
ARIA attribute unsupported by role

An aria-* attribute is not permitted on the element role.

Fix. Remove the attribute, choose the role that supports it, or use the element the role implies.

CORALITE-A105 warning
Nested interactive element

An interactive element is nested inside another interactive element.

Fix. Split the nesting: use a non-interactive wrapper, or make only one element focusable.

Configuration 3

Configuration diagnostics
Code Severity Diagnostic
CORALITE-CFG-001 error
Unknown CSP mode key

A key in csp.modes is not one of development, testing or production.

Fix. Rename the mode key to a supported environment name.

CORALITE-CFG-002 error
Recursive CSP modes

A csp.modes entry declares a nested modes key.

Fix. Move the directives directly onto the mode object; modes cannot nest.

CORALITE-CFG-003 error
Unknown CSP configuration key

A csp.modes entry contains a key that is not a valid CSP option.

Fix. Use a supported CSP key such as enabled, directives or externalStyles.