FUI9010: Fragment definition is not valid
criticalThe compiler refused a .fragment definition because it failed Core's schema.
Details
{
"code": "FUI9010",
"ruleId": "fragment/invalid-definition",
"category": "System",
"defaultSeverity": "critical",
"lifecycle": "experimental",
"fixAvailable": false,
"evidenceRequired": false
}Guidance
What it means
The compiler tried to load a .fragment / .fragment.ts / .fragment.tsx
file and Core rejected the definition. FUI9010 is a schema refusal, not a
style finding: the file did not describe a fragment the compiler is allowed
to compile. Evidence lists the definition name, the authoring API
(v1, v2, governed, or v3), and the schema issues.
Typical causes:
- a required field is missing or the wrong type
- a v3 state or relation points at an identifier the schema does not accept
annotationsor_provenanceappear where the current contract forbids them- the file mixed an older
defineFragmentshape with v3 fields
How to resolve it
Fix the authored definition so it matches the schema for its API. Do not narrow the schema or delete fields to silence the code. Use the issue paths in the finding — they name the exact field the loader refused.
If you are migrating onto v3, compile with the same loader the CLI uses
(npx @usefragments/cli build / check) rather than a hand-rolled import.
The public JSON schema for fragment definitions is published with Core; the
explain page for this code is the human counterpart.
When an exception is intentional, attach a line-level, reasoned suppression from the configuration reference. Do not exclude the whole fragments directory.
Verify the change
Run npx @usefragments/cli check --changed --format agent, confirm the
definition loads without FUI9010, then run
npx @usefragments/cli check --changed --ci.
Intentional exception? Use a narrow, reasoned directive from the in-source suppression reference.