| Blank calendar or “no plugin provides the view” | Register the matching plugin and use an exact view name. React plugins require remounting if changed. |
| Unstyled or compressed layout | Import z-cal/style.css. Inspect host/container dimensions and CSS overrides. |
| Month cells leave unused vertical space | Set height; for '100%', define the parent's height and the React host's height. Use dayMaxEvents: true for uniform crowded rows. |
| Responsive week still shows seven narrow columns | Enable responsiveWeek; use timeGridWeek or a view inheriting it. Resource week views do not implement this option. |
| Custom event text overlaps neighboring columns | Keep custom content within the event width using clipping/ellipsis and shrinkable flex children; preserve the built-in cx-event-time/cx-event-title classes where useful. |
| “requires the Temporal API” | Import z-cal/polyfill before using the library in that runtime. |
getTime() is missing | Callback dates are Temporal values. Use toString() or epochMilliseconds on a zoned value; all-day dates are PlainDate. |
| Event appears at the wrong time | Check the calendar timeZone and whether the input includes an offset. Offset-free inputs represent wall-clock time; UTC inputs represent an instant. |
| All-day event ends a day early | Ends are exclusive. A one-day event on September 7 ends on September 8. |
| Timed event has no duration | Supply end. Missing timed ends are point events, not implicitly one-hour events. |
| Cannot drag/select/resize | Register Interaction; set editable and/or selectable. Check per-event overrides and synchronous constraints. |
| Drag selection shows a highlight but no event/form | Implement the select callback, open your form, and call addEvent or update application state. |
| Editor closes or highlight disappears when clicked | Use unselectCancel for the editor selector, or unselectAuto: false and explicit unselect() after save/cancel. |
| Events disappear after a React render | Keep unchanged arrays stable and decide whether React state or the instance owns edits. A replacement events prop is authoritative. |
| In-place array mutation does not update the view | Use a new array/object for intentional React changes, or use the instance API. |
| Remote refresh overwrites local edits | Persist edits before refetching and ensure the server returns them. Stable IDs retain mounted elements, not unsaved server data. |
| Source stays loading | Return a promise or call success/failure from callback sources. Do not leave them unsettled. |
| JSON feed has no events | Return an array, check the requested range/timezone, HTTP status, console errors, and CORS. Use a function source for custom auth headers. |
updateEvent({ id, title }) fails or loses fields | It is a replacement operation requiring start. Preserve the complete input fields you want to retain. |
| React import cannot be resolved | Install z-cal, then import z-cal/react. Install React/React DOM 19; do not install the subpath as a package. |
| SSR output contains only an empty div | Expected: the calendar grid mounts on the client. Keep direct DOM calls out of server rendering. |
| New plugin prop does not change available views | Remount <Calendar> with a different key; plugins are fixed per instance. |
| CSS utilities do not override calendar styles | Check cascade-layer order; see styling. |