Troubleshooting — Veldform — vanrossum.dev                    

       vanrossum.dev 

Troubleshooting — Veldform
==========================

  [home](https://vanrossum.dev)/[veldform](https://vanrossum.dev/products/veldform)/docs 

Veldform / Docs

Troubleshooting
===============

- [The log](#the-log)
- [Common issues](#common-issues)
    - ["Security check failed. Please reload and try again."](#security-check-failed-please-reload-and-try-again)
    - [Submissions seem to disappear](#submissions-seem-to-disappear)
    - ["The spam check could not verify your submission."](#the-spam-check-could-not-verify-your-submission)
    - ["We could not complete your submission. Please try again."](#we-could-not-complete-your-submission-please-try-again)
    - [Notifications don't arrive](#notifications-dont-arrive)
    - [A payment is stuck on "Awaiting payment"](#a-payment-is-stuck-on-awaiting-payment)
    - [Forms don't submit at all](#forms-dont-submit-at-all)
    - [The form works without styling, or JS features don't work](#the-form-works-without-styling-or-js-features-dont-work)
    - [Updates don't show up](#updates-dont-show-up)

The log
-------

Before anything else: check the log. Veldform keeps an activity log of everything that happens — actions that ran, were skipped or failed, API requests that errored, captcha failures and payment updates. You'll find it under `Veldform` -> `Log`, and a per-entry version in each entry's timeline.

Log entries are kept for 30 days (adjustable with the `veldform/log/retention_days` filter). Sensitive values are never logged.

Common issues
-------------

### "Security check failed. Please reload and try again."

The security token of the form expired. The usual culprit is page caching: a cached page serves an old token. Exclude pages with forms from full-page caching, or lower the cache lifetime — WordPress tokens are valid up to 24 hours.

### Submissions seem to disappear

If a test submission shows a success message but no entry or notification appears, you most likely tripped the [anti-spam protection](/products/veldform/docs/anti-spam) — bots (and admins testing very quickly) get a fake success on purpose. Wait a few seconds between loading the page and submitting.

Also check the form's `Settings` -> `Entries`: when `Store submissions as entries` is off, submissions only run actions and are not stored.

### "The spam check could not verify your submission."

The captcha check failed. Verify the site key and secret key under `Veldform` -> `Settings` -> `Spam protection` match your provider's dashboard. With reCAPTCHA v3, real users with a low score can be affected — you can lower the threshold via the `veldform/captcha/recaptcha_min_score` filter.

### "We could not complete your submission. Please try again."

An action marked as `Required` failed. Open the log — you'll find an `action.failed` event with the details (for API actions, including the request and response).

### Notifications don't arrive

Notifications are sent through `wp_mail()`, like all WordPress email. First confirm the action actually ran (check the log). If it did, the problem is email delivery: many hosts have poor deliverability out of the box. Install an SMTP plugin or a transactional mail service, and make sure your From address uses your own domain.

### A payment is stuck on "Awaiting payment"

Payment confirmation comes from the provider's webhook. If entries stay on `Awaiting payment` even though the payment succeeded, the webhook isn't reaching your site — check that your site is publicly reachable and that no security plugin blocks `/wp-json/`. Abandoned checkouts are automatically marked expired after 24 hours.

### Forms don't submit at all

Submissions go through the WordPress REST API. If a security plugin, firewall or CDN blocks `/wp-json/`, submissions will fail. Make sure the `veldform/v1` namespace is reachable.

### The form works without styling, or JS features don't work

The form is built with progressive enhancement: it submits fine without JavaScript, but live validation, conditional logic, captcha and dynamic dropdowns need the `veldform.js` script. Check for JavaScript errors in the browser console, and for optimization plugins that exclude or defer the script incorrectly. If the styling is missing, check whether something is dequeuing the `veldform` stylesheet (or whether the `veldform/render/styles` filter is in play).

### Updates don't show up

Plugin updates require an active license. Check your license key under `Veldform` -> `Settings` — see [Installation](/products/veldform/docs/installation).

   © 2026 Jeffrey van Rossum · [privacy](https://vanrossum.dev/privacy) · [terms](https://vanrossum.dev/terms) · [cookies](https://vanrossum.dev/cookies) [𝕏](https://x.com/jeffreyrossum) [YouTube](https://www.youtube.com/@jeffrey.rossum) [GitHub](https://github.com/jeffreyvr) [LinkedIn](https://www.linkedin.com/in/jeffrey-van-rossum-97b27321) [Instagram](https://www.instagram.com/jeffrey.rossum/) [Nomads](https://www.nomads.com/@jeffreyrossum/) [Unsplash](https://unsplash.com/@jeffreyrossum) 

 made with ☕