Troubleshooting.

Every package exception extends ChecklistException. Start with its concrete class and the model's current state when a checklist operation fails.

The application fails during boot

InvalidConfigurationException at boot usually means checklist.table_names is missing a required key or contains a blank value. Republish the config or compare your copy with the installed package version.

An invalid notification class or recipient resolver may surface when its event first dispatches. Notification overrides must extend Laravel's Notification; the resolver must implement RecipientResolver.

Publication rejects a template

TemplateValidationException names the item, section, key, operator, or rule graph that failed. Common causes are:

• a section deeper than checklist.max_section_depth;
• a duplicate key or a visibility target that does not exist;
• Below or Above on a non-numeric item;
• a rating without distinct bounds or a select without valid options;
• a visibility rule targeting its source or closing a cycle.

The first builder publication rolls back every inserted row. A later draft remains editable after a failed publication.

Published structure will not update

PublishedVersionException means the version, item, section, or rule is frozen. Call newDraft(), edit the copied rows through model instances, then publish the draft.

Do not switch to a mass query update. It bypasses model events and can alter history that existing checklists still reference.

An answer is rejected

InvalidAnswerException means the value does not match the item's handler. Check the exact item type and config on the checklist's pinned version.

Pass/fail does not accept yes; rating accepts whole numbers only; date accepts Y-m-d; select accepts configured option values and requires an array for a multiple select.

ChecklistStateException means the checklist is closed, the item belongs to another version, the version is still a draft, or the requested lifecycle transition is invalid.

Submission is incomplete

Catch IncompleteChecklistException and render every entry in $unmet. Each entry provides itemId, itemLabel, reason, and describe().

An answered item may still need a non-blank note or an evidence row of the required type. Hidden items and hidden answers do not block submission.

Evidence cannot be stored

EvidenceException distinguishes an invalid upload, unreadable content, unknown evidence type, wrong response or checklist, and filesystem failure.

Confirm that checklist.evidence.disk names a configured writable disk. The package removes executable extensions from stored names, so a missing original extension is expected for refused file types.

Notifications do not arrive

Check CHECKLIST_NOTIFICATIONS, the event override map, and the recipient resolver. The default creation event has no recipient. Other default routes usually require an assigned notifiable model.

The shipped notification uses both mail and database. Ensure the notifications table exists and the notifiable has mail routing. Delivery exceptions are reported through Laravel's exception handler instead of rolling back the checklist operation.

A schedule creates nothing

Confirm active is true, next_due_at is not null and is due, and the template has a published version. With SkipWhileOpen, any pending or in-progress checklist from that schedule suppresses the occurrence.

Run php artisan checklist:generate-due manually and read warnings for unpublished templates.

Audit verification fails

The verifier reports whether a row's predecessor, content hash, or checklist head disagrees. Preserve the database and backups before investigating. The package has no automatic repair command because rewriting a chain removes the evidence of the change.

What to read next

• Configuration for valid keys and defaults.
• Console commands for operational command behavior.
• Enums and contracts for exception families and supported values.