> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and resolve common Nextedy CHECKLIST configuration and runtime issues.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Checklist Displays as Read-Only

**Symptom:** The checklist UI shows items but does not allow editing. The interface indicates the checklist is read-only.

**Possible causes and solutions:**

| Cause                                                     | Solution                                                                                                                                                                                                        |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Custom field marked as read-only by work item permissions | Check **Administration > Work Items > Permissions** and verify the field is not in a read-only state for the current role                                                                                       |
| Field listed in **Administration > Read Only Fields**     | Remove the checklist custom field from the read-only fields list                                                                                                                                                |
| Form extension not configured correctly                   | Verify the form extension is properly set up. The checklist requires both the custom field and the form extension to be configured. See [Work Items Checklist](/checklist/getting-started/work-items-checklist) |
| Checklist frozen by status                                | Check if `nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate=false` is set for the current status. See [Freezing Checklists by Status](/checklist/guides/freeze-by-status)                                |
| Document type changed after creation                      | Changing a document type post-creation may cause field type inconsistencies. Create documents from templates with the correct type from the start                                                               |

<Tip title="Check the simplest cause first">
  Most read-only issues are caused by field permissions or the read-only fields configuration in Polarion Administration. Verify these before investigating more complex causes.
</Tip>

## Checklist Not Appearing on Work Item

**Symptom:** The work item form does not show the checklist at all.

**Diagnosis steps:**

1. Verify the **custom field** exists and is of type `Text (multi-line plain text)`.

2. Verify the **form extension** is added to the work item type's form layout with the correct `checklistId` attribute.

3. Confirm the custom field ID in the form extension matches the actual field ID.

4. Check that the Nextedy CHECKLIST license is valid and active.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/Jklvz9qm2AdmIvBG/checklist/diagrams/guides/troubleshooting/diagram-1.svg?fit=max&auto=format&n=Jklvz9qm2AdmIvBG&q=85&s=b20d0f35124ca5366690e4ea85357155" alt="diagram" style={{ maxWidth: "740px", width: "100%" }} width="740" height="180" data-path="checklist/diagrams/guides/troubleshooting/diagram-1.svg" />
</Frame>

<Warning title="Custom field type is critical">
  The checklist custom field **must** be type `Text (multi-line plain text)`. Using any other type (Rich Text, String, etc.) causes the checklist to fail with a type validation error. If you see an error message about field type mismatch, recreate the custom field with the correct type.
</Warning>

## Template Not Applied to Checklist

**Symptom:** The checklist appears empty or does not show the expected template items.

**Diagnosis steps:**

1. Verify the template configuration property is set correctly:
   ```properties theme={null}
   nextedy.checklist._TYPEID._FIELDID.workItemTemplateId=TEMPLATE-ID
   ```

2. Confirm the template work item exists and contains checklist data.

3. Check the property hierarchy -- a more specific property may override the global default:
   ```properties theme={null}
   # Most specific (type + field)
   nextedy.checklist.userstory.dod.workItemTemplateId=DOD-100
   # Field-specific (any type)
   nextedy.checklist.dod.workItemTemplateId=DOD-99
   # Type-specific (any field)
   nextedy.checklist.userstory.workItemTemplateId=DOD-98
   # Global default
   nextedy.checklist.workItemTemplateId=DOD-97
   ```

4. Verify that template merging is not disabled for the current status via `nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate=false`.

5. Check if `nextedy.checklist._TYPEID._FIELDID.mergeTemplateResolved=false` is preventing merging on resolved items.

<Warning title="Modifications to template work items affect all instances">
  Changes to the checklist on the template work item cascade to all work items using that template. Be cautious when editing template source work items, and consider using a dedicated project for template storage.
</Warning>

## Workflow Transition Blocked by Checklist

**Symptom:** A workflow transition fails with a message about unchecked checklist items.

**Resolution:**

1. Open the work item and review the checklist. Look for items with an Empty or NOK result state.

2. If using `ChecklistAllChecked` condition, **every** item must be checked (OK state). Both checked and conditional states count as checked.

3. If using `ChecklistMandatoryChecked` condition, only mandatory items (marked with ) must be checked.

4. If multiple checklist fields are specified in the condition (comma-separated), **all** checklists must pass validation (AND logic).

5. Verify the `checklist` parameter in the workflow condition matches the actual custom field ID (not the display name).

<Tip title="Check the error message carefully">
  The workflow condition provides a user-friendly error message that identifies which specific checklist has unchecked items. Use this to pinpoint the blocking checklist when multiple checklists are configured.
</Tip>

## Summary Field Not Updating

**Symptom:** The `{checklistId}_summary` field does not reflect the current checklist state.

**Diagnosis:**

1. Verify the summary field exists on the work item type (e.g., `dod_summary` for checklist ID `dod`).

2. Check that the checklist ID is included in the summary field configuration.

3. Ensure the save hook is not disabled via `nextedy.checklist.disable.hook`. Disabling the save hook stops summary field synchronization.

4. Save the work item again -- the summary field updates on every save operation.

<Note title="Summary fields enable search">
  Summary fields provide a text representation of the checklist state, enabling Lucene full-text search across checklist content in Polarion. If search is not returning expected results for checklist data, verify the summary field is properly configured and updating.
</Note>

## Save Hook Conflicts

**Symptom:** Errors in the Polarion log related to save operations, potentially affecting other extensions.

If multiple Polarion extensions use save hooks simultaneously, EHCache conflicts may occur. To work around this:

```properties theme={null}
nextedy.checklist.disable.hook
```

<Warning title="Trade-offs of disabling the save hook">
  Disabling the save hook removes:

  * Automatic checklist reset on work item type change
  * Summary field synchronization

  Core checklist functionality (editing, templates, workflow functions, conditions) continues to work normally.
</Warning>

## Checklist Not Loading in Bulk Edit Mode

**Symptom:** When selecting multiple work items of different types and opening the bulk editor, the checklist field is not displayed.

This is intentional behavior introduced in version 24.9.0. Checklists do not load in mixed-type bulk edit mode to prevent template corruption when different work item types share the same checklist field ID.

**Workaround:** Select work items of a single type before using the bulk editor, or edit checklists individually.

## Verification

You should now see:

* The specific troubleshooting section matching your issue provides clear diagnostic steps
* Following the resolution steps resolves the problem
* If the issue persists, the configuration property references point you to the relevant administration pages

## See Also

* [Work Items Checklist](/checklist/getting-started/work-items-checklist) -- Initial setup guide for work item checklists
* [Creating and Managing Templates](/checklist/guides/templates) -- Template configuration reference
* [Workflow Gates and Validation](/checklist/guides/workflow-gates) -- Workflow function and condition setup
* [Read-Only Mode](/checklist/guides/readonly-mode) -- Understanding read-only behavior
* [Freezing Checklists by Status](/checklist/guides/freeze-by-status) -- Status-based checklist freezing
* [Reset on Work Item Type Change](/checklist/guides/type-change-reset) -- Type change reset configuration

<LastReviewed date="2026-07-02" />