# Troubleshooting

## Content

Use this page when Scheduler does not behave as expected. Each section starts with the visible symptom, then lists the likely cause and the checks that usually identify the problem.
Before investigating a specific symptom, verify that the host has a non-zero height, Wijmo CSS is loaded, `itemsSource` is assigned, `start` and `end` map to valid `Date` values, `displayDate` is set, and the active `definition` is valid.

## The control does not render

### The Scheduler area is blank

**Likely cause:**
The host has no usable height, the stylesheet is missing, or a module failed to load.
**What to check:**
Confirm that the host exists when `FlexScheduler` is constructed, has a non-zero height, and is visible. Confirm that `@mescius/wijmo.styles/wijmo.css` is loaded. For native ES modules, verify import-map entries for `@mescius/wijmo`, `@mescius/wijmo.input`, and `@mescius/wijmo.scheduler`.

### The browser reports a module resolution error

**Likely cause:**
A package imported by `@mescius/wijmo.scheduler` is not mapped or unavailable in the build.
**What to check:**
Bundlers should resolve `@mescius/wijmo` and `@mescius/wijmo.input` from package metadata. Native ES modules require explicit import-map entries.

## Events and dates are incorrect

### Events do not appear

**Likely cause:**
The data source is empty, field mappings do not match, or dates are invalid.
**What to check:**
Verify `itemsSource`, mapped `start` and `end` properties, valid `Date` values, and `start < end`. Convert serialized server dates before binding. Set `displayDate` to a date covered by the data.

### Event times are shifted

**Likely cause:**
`displayDate`, `timeZone`, or server-side UTC/local conversion is inconsistent.
**What to check:**
Confirm the Scheduler `timeZone` and the policy used to create each `Date`. Do not mix local-clock values and UTC instants without explicit conversion.

### One event is displayed as several fragments

**Likely cause:**
The event spans multiple dates or resource sections.
**What to check:**
This is normal in layouts that split events. Treat fragments as one source item and update it.

## Views and resources are incorrect

### A resource lane is empty

**Likely cause:**
The event value, resource descriptor, and axis binding do not use the same field or identifier.
**What to check:**
Confirm `fieldExpr`, the value in `dataSource`, and the active `definition` binding. For multi-value resources, verify `allowMultiple: true` and an array-valued property.

### A custom definition does not render

**Likely cause:**
Repeated axis identities or invalid Timed layout rules.
**What to check:**
Call `planSchedulerProjection` and inspect `integrity.level` and `integrity.reasons`. Timed layouts require one `time:hour` binding.

### A custom definition has unexpected grouping

**Likely cause:**
`time:hour` shares an axis with another binding and the layout is normalized.
**What to check:**
Move the other binding to the opposite axis.

### Working hours have the wrong effect

**Likely cause:**
`workDays` takes precedence over `workHours`, or the application expects non-working cells to be hidden.
**What to check:**
Clear or update `workDays`. Working-time settings style cells but do not hide them; use a time binding's `visible` callback to omit axis items.

### Synchronized schedules drift out of alignment

**Likely cause:**
The two Schedulers use different definitions or different bindings on the synchronized axis, so the same scroll offset represents a different position.
**What to check:**
Use the same definition on both Schedulers, or keep the bindings on the synchronized axis consistent. Verify `scrollingSyncDirection` on the instance that holds the partner reference.

## Editing and pointer interaction fail

### Changes are not committed

**Likely cause:**
Validation or a cancelable event rejected the request.
**What to check:**
Inspect `itemChanging` and `conflictChecked` for `args.cancel`, verify start/end validation, and reconcile the collection after server rejection.

### Dragging or resizing does nothing

**Likely cause:**
The relevant option is disabled or the layout does not support the operation.
**What to check:**
Verify `allowDragEvent` and `allowResizeEvent`. Summary views support moving but not resizing.

### Conflicts are reported but the operation is allowed

**Likely cause:**
Conflict detection always runs. A detected conflict does not block the operation unless the application cancels the request.
**What to check:**
Set `args.cancel = true` in `conflictChecked` to reject the candidate. Keep server-side validation authoritative.

## Display customization and keyboard behavior

### Custom event content is unsafe or malformed

**Likely cause:**
Dynamic values were inserted into an `itemTemplate` HTML string without escaping.
**What to check:**
Escape user-provided values and base commands on the source item rather than rendered fragments.

### A context-menu command is disabled

**Likely cause:**
`canExecute` returns `false` for the current target or action.
**What to check:**
Inspect `hitTestType` and call the base implementation for built-in actions.

### Keyboard focus is lost after CRUD

**Likely cause:**
The item left the current view or replacement UI changed the document Tab order.
**What to check:**
Preserve the normal Tab sequence and verify the documented focus fallback.

## Collect diagnostic information

When reporting an issue, include the active definition key, display date, time zone, item count, one representative source item, mapped field names, resource descriptors, and the browser console error.
Avoid logging sensitive event descriptions or location data.