Troubleshooting

"I added a field but it doesn't appear in the form"

The field exists in the schema but you haven't added it to the form designer. Open Entity → Form tab → +Add field and pick the new field from the dropdown. Save the form.

"The Reconciler is stuck on a long-running operation"

Schema changes on big tables (5M+ rows) can take minutes. Check PF Manage → Reconciler for the current operation. If progress is moving (rows-affected counter ticking up), wait. If it has stalled, the cron worker that drains the Reconciler queue may have died — restart it with PF Manage → Reconciler → Resume worker.

"Records list is slow"

Common causes:

1. Missing index on the field you're sorting / filtering by. Enable the Indexed checkbox on that field in the schema. The Reconciler adds the DB index in the background.
2. Too many fields per row. Use sparse fieldsets via the list designer ("Show only these columns") so the list query SELECTs less data per row.
3. N+1 on relations. The list view auto-batches relation loads; if you wrote a custom field formatter that re-queries per row, that's your culprit.

"Can't delete an entity — gets fk_protected"

Another entity has a Relation field pointing at this one. The error response includes the list of referring entities and fields so you know who. Either:

• Remove the Relation field(s) first (or change them to point elsewhere).
• Set the Relation's on_target_delete to set_null or cascade, then delete (the Reconciler will apply the cascade correctly).
• Force with --no-fk-check in the REST call. Dangerous — you will end up with broken references.

"Workflow doesn't fire on record events"

Check:

1. WP-PFWorkflow is installed and licensed (required for any pfm.* trigger to be available).
2. The workflow is active (toggle at top-right of the editor).
3. The trigger's entity slug filter matches the entity you're creating records in. Slug typos are silent.
4. Setyenv → Executions — does an execution appear at all when you create a record? If yes but it failed immediately, fix the workflow itself. If no, check wp_pfw_idempotency — a leftover row from a previous run with the same key would short-circuit.

"Inline cell edit fails with validation_error"

The save went through the same validators the form uses. The error message in the inline tooltip lists which rule failed. Open the full form (double-click the row's left edge) for a richer error display + more context.

"I see two events fired for the same change"

Almost certainly: a workflow that listens to pfm.record.changed itself modifies the record. That's a loop. Add a Condition node at the start of the workflow that exits early when the diff is "the field I would write to is already at the target value".

"CSV import says column_unmapped for fields I clearly mapped"

The CSV header column name didn't auto-match the field slug. Use the mapping step's dropdown to map manually. If your headers differ between imports, save the mapping as a template on the first import; future imports of the same shape reuse the template automatically.