Audience: Contributor
Symptom → cause → fix for page trees, catalog sync, and codegen. Commands live on Operations.
See also: Overview · Operations · Change playbooks
| Symptom | Likely cause | Fix |
|---|---|---|
| Cannot drop inside a host | No catalog definition.children (children.json / &def.children missing) |
Add children.json (even []) and restart API, or drop as sibling |
| AJV warns about children | Child type not in parent’s schema anyOf |
Check Catalog Schema children; move or change type |
| AJV warns about unknown property | Extra key on node (additionalProperties: false) |
Remove invented fields (id, className, …) |
| Inserted element missing defaults | Hand-built JSON omitted children.json starter |
Copy from the element’s children.json |
| Text not visible | Used a string child or wrong prop | Use text + html prop with { "raw": "…" } |
| Block shows empty / wrong | Expanded master stored on instance, or bad blockId |
Persist reference shape only; fix blockId (Blocks and reuse) |
| Styles ignored | Wrong breakpoint or css vs attr |
Switch device; confirm prop type |
| Binding shows blank | Bad expr, empty data source, or both raw+expr |
See Values and bindings; preview with data |
| Save succeeds despite bad tree | Validation is warn-only | Fix the tree; do not rely on the API to reject |
| Symptom | Likely cause | Fix |
|---|---|---|
| New type missing from palette | Forgot schemas:page, or DbInit stale, or palette: false |
Run schemas:page, restart API; check &def.palette |
New type missing from page.schema.json |
Page schema not regenerated | cd server/main && npm run schemas:page |
| Property panel wrong widget | Missing &def options / editorType |
See Schema and editors; restart after DbInit |
| Canvas render wrong / missing | Templates not regenerated after render change |
npm run generate:templates from repo root |
| Wiki catalog stale | Generated file not refreshed | npm run schemas:wiki-catalog |
builder / lkt-block not in DB elements |
Expected — DbInit skips builder/ |
Create instances via BlockOps / block UI |
# Regenerate page AJV union
cd server/main && npm run schemas:page
# Full schema sync (charts + standardize + children def + page)
cd server/main && npm run schemas:sync
# Refresh wiki element catalog
cd server/main && npm run schemas:wiki-catalog
# Check catalog + wiki docs drift
cd server/main && npm run schemas:wiki-catalog:check
cd server/main && npm run schemas:wiki-docs:check
# Canvas templates (repo root)
npm run generate:templates
Restart the API after schema edits so DbInit reloads the element catalog.