Troubleshooting & FAQ
Where do I build the form fields?
Section titled “Where do I build the form fields?”In the form’s config JSON, either as raw JSON or through the structured editor. OctaForms has no drag-and-drop builder on purpose. It is a backend engine aimed at people who render their own markup. See Building forms.
Why is there no email field type?
Section titled “Why is there no email field type?”Because email is a validation rule, not a field type. An email field is a text field with the email rule. The same goes for numbers and URLs. See Field types.
A legitimate submission landed in the spam quarantine
Section titled “A legitimate submission landed in the spam quarantine”Almost always this is browser autofill filling the honeypot field for a real visitor. Recover the submission from Submissions → Spam quarantine (recovering it also sends its emails and webhooks), then rename the honeypot field to something autofill never targets. The config validator warns about risky names. See Anti-spam.
The form says the security token is unreachable
Section titled “The form says the security token is unreachable”A security plugin or firewall is blocking /wp-json/ for visitors. Site Health runs a loopback self-test of the token endpoint and reports this explicitly. Allow the OctaForms REST routes through. As a last resort, a form can set "requireToken": false in its config; honeypot and rate limiting stay active. See the token contract.
Emails are marked “sent” but never arrive
Section titled “Emails are marked “sent” but never arrive”“Sent” only means your server’s mail transport accepted the message. It says nothing about delivery. Install an SMTP plugin and set up SPF and DKIM for your sending domain, and send from an address on your own domain. See Email deliverability.
Submissions arrive late
Section titled “Submissions arrive late”Delivery that is not sent inline waits for cron, and WP-Cron only runs on traffic. Set up a real system cron running wp octa-forms queue drain every minute. Nothing is lost in the meantime, it is only delayed. See Cron and the delivery queue.
My own form markup does not submit, but the shortcode works
Section titled “My own form markup does not submit, but the shortcode works”That points at your integration rather than the plugin. Check that each input’s name matches a field name in the config, that your form has data-octa-forms="slug" if you use the helper, and that you are following the token and serialization contract if you wrote your own JavaScript. Dropping [octa_form slug="…"] on a page is the quickest way to confirm the form config itself is fine. See Three ways to add a form.
Can I change a form’s slug after publishing?
Section titled “Can I change a form’s slug after publishing?”No. The slug locks at publication because it is the contract your theme and webhook receivers rely on. Create a new form if you need a different slug. See Getting started.
A webhook fired twice
Section titled “A webhook fired twice”Delivery is at-least-once, so under retries a webhook can arrive more than once. Your receiver must deduplicate on the payload’s id. See Webhooks.
How do I hide the callback widget on checkout?
Section titled “How do I hide the callback widget on checkout?”Return false from the octa_forms_callback_visible filter for those requests. See Callback widget.
Is my data removed when I uninstall?
Section titled “Is my data removed when I uninstall?”Only if you choose it. Full data removal on uninstall is opt-in, so uninstalling to troubleshoot will not wipe your submissions by surprise. See Privacy & GDPR.