Forms troubleshooting
The form does not show
| You see | Why | Fix |
|---|---|---|
| Nothing (visitors) | The form's arguments are wrong. | Sign in as an administrator: CAFE shows the problem there. |
| "Please log in to use this form." | Not signed in, and the form is not a visitor form. | Sign in, or set allow_guests (create forms). |
| "You are not allowed to use this form." | The user may not create/edit this object, or lacks the form's capability. |
Check the role's capabilities; see Security. |
| "There is no dynamic form "x"." (admins) | The ID is not registered or made in CAFE → Forms. | Check the ID; register on init. |
| The shortcode prints nothing | Shortcodes only show registered / CAFE → Forms forms. | Register the form. |
| Fields are missing | Inactive field group, media fields for people without upload_files, or cafe_dynamic_form_fields. |
Activate the group; see Media. |
Nothing is saved
- Read the messages at the top of the form and under the fields.
- "This form has expired. Please reload the page and try again.": the nonce is older than a day (or the page came from a full-page cache for another user). Exclude pages with forms from full-page caching, or reload.
- "This form could not be verified.": the signed settings changed: the page is cached from before the site's secret keys changed, or something edited the hidden input. Clear the page cache.
- "Your submission could not be sent.": the hidden honeypot input was filled in (a bot, or a browser extension that fills every input).
- Required fields hidden with CSS or conditional logic still count as required (conditional logic is not evaluated yet).
Pickers show "Could not load items"
The picker searches /cafe/v1/forms/references. Check that the REST API is
reachable on the front end (security plugins sometimes block it for visitors)
and that the user may use the form.
The media library does not open
Only people with upload_files get media fields. If the button does nothing,
check the browser console: themes that dequeue WordPress's media scripts on
the front end break the library.
Styles look wrong
The fields use CAFE's field stylesheet; strong theme rules for input,
select or label can win. Scope your fixes to .cafe-form
(Layout).
Checking a form in the browser
Automated tests cover the PHP side; please check these by hand on your site (theme, caching and other plugins differ):
- The form renders with your theme; tabs, widths and labels look right.
- Required field left empty → message under it, nothing saved.
- Every field type in the form: fill in, send, reload; the value is there.
- Media: upload, choose, remove (as a user with
upload_files). - Collections: add, reorder, remove items; send; reload.
- Pickers: search, pick, remove.
- Without JavaScript (browser setting): send → success message after reload.
- Double-click the button → one post.
- As a user who may not use the form → the message, no form.