Troubleshooting

Check these in order:

1. Form is active — open the form in your dashboard and make sure the status shows "Active". Inactive forms reject all submissions.
2. Correct action URL — your HTML form's action attribute must point to https://formblade.com/f/your-form-link-id. Check for typos.
3. Method is POST — forms must use method="POST". GET requests show the hosted form page instead of submitting data.
4. Monthly limit not reached — Personal plan allows 300 submissions/month, Pro allows 3,000. Check your usage in the dashboard stats bar.
5. Not blocked by spam protection — if you have captcha or honeypot enabled, test with them temporarily disabled to rule out false positives.

FormBlade has multiple spam detection layers. A submission is flagged if any check fails:

• Honeypot triggered — the hidden _fb_hp field was filled in. This usually means a bot. If your CSS accidentally makes this field visible, users may fill it in by mistake.
• JS honeypot failed — the JavaScript verification token was missing or invalid. This happens with bots that don't execute JavaScript, or if the FormBlade script is blocked by an ad blocker.
• Captcha failed — the captcha response was missing, expired, or invalid. See the Captcha section below.

Check the spam_flags column on individual submissions to see which check triggered.

This means the form is inactive or doesn't exist. Go to your dashboard, find the form, and check that:

• The form status is set to Active
• The form link ID in the URL matches your form's link ID
• The form hasn't been deleted

FormBlade stores whatever fields are submitted via POST. If fields are missing or have wrong names:

• Make sure every input has a name attribute: <input name="email">
• Check for duplicate field names — only the last value is stored
• If using the hosted form designer, fields are defined in the Designer tab. HTML form fields are independent of the designer.

The most common causes:

1. Email not verified — you must verify your account email before notifications are sent. Check for the verification banner in your dashboard.
2. Check spam/junk folder — notification emails sometimes land in spam, especially with custom SMTP on the Personal plan (which includes FormBlade branding).
3. No notification email set — open the form's Settings tab and make sure a notification email address is entered.
4. Custom SMTP misconfigured — if you connected a custom email provider, test it using the "Send test email" button in the form settings.

Notifications are processed by a background queue and typically arrive within a few seconds. Delays can happen if:

• Your email provider is throttling or queuing messages
• The receiving mail server has greylisting enabled (delays first-time senders)
• High submission volume is being processed

If emails consistently take more than a minute, try switching to a different email provider in your Email Setup.

1. Make sure you completed the Telegram bot setup: open the form's Settings tab and follow the Telegram connection steps.
2. Verify you sent /start to the FormBlade bot before connecting.
3. Check that the chat ID is correct — reconnect if unsure.
4. Telegram notifications only work if the form is active and has at least one non-spam submission.

If legitimate users can't submit your form because of captcha errors:

• Wrong keys — make sure the site key and secret key match your captcha provider's dashboard. They are separate values and must not be swapped.
• Domain not authorized — in your captcha provider (reCAPTCHA, hCaptcha, Turnstile), add both your website domain and formblade.com to the allowed domains list.
• reCAPTCHA v3 score too high — if using reCAPTCHA v3, lower the minimum score threshold (default is 0.5). Some legitimate users score lower on mobile devices.
• Math captcha — the math challenge is the simplest option and works without any provider keys. Try switching to it if other providers cause issues.

The honeypot field (_fb_hp) is a hidden input that should be invisible to real users. If it's being triggered:

• Check your CSS — make sure the honeypot field is not visible. It should have display: none or equivalent.
• Some browser autofill extensions may fill hidden fields. If this is a recurring issue, rename the honeypot field in the form's Settings tab to something less generic.
• You can disable the honeypot entirely in Settings, though this reduces spam protection.

• File too large — Personal plan: 1 MB per file. Pro plan: 25 MB per file. Compress or resize before uploading.
• Storage full — Personal: 100 MB total. Pro: 1 GB total. Delete old submissions with attachments to free space, or check your usage on the Storage page.
• Empty file input — if a file input has no file selected, it is skipped automatically. This is normal and not an error.

This is almost always a transfer encoding problem. The file field appears in the submission, but the actual file contents are missing.

HTML forms: missing enctype

Your <form> tag must include enctype="multipart/form-data". Without it, the browser defaults to application/x-www-form-urlencoded, which cannot transmit binary file data — it sends only the filename as a text string.

<!-- Wrong — files will not upload -->
<form action="https://formblade.com/f/contact" method="POST">

<!-- Correct -->
<form action="https://formblade.com/f/contact" method="POST"
      enctype="multipart/form-data">

Replace /f/contact with your own form link from the dashboard.

JavaScript: manually setting Content-Type

When using fetch or XMLHttpRequest with a FormData body, do not set the Content-Type header yourself. The browser must generate it automatically so it includes the correct multipart boundary string.

const data = new FormData(document.querySelector('form'));

// Wrong — overrides the boundary, server can't parse the files
fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'multipart/form-data' },
  body: data
});

// Correct — let the browser set Content-Type
fetch(url, {
  method: 'POST',
  body: data
});

JavaScript: serializing FormData to JSON

Passing JSON.stringify(formData) or building a plain object from form values discards all file data. Send the FormData instance directly as the request body.

// Wrong — files are lost
fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Alice' })
});

// Correct — files are included
const data = new FormData(form);
fetch(url, { method: 'POST', body: data });

How to verify

Open your browser's developer tools (F12 → Network tab), submit the form, and click the request. Check:

• Content-Type header should be multipart/form-data; boundary=...
• Request payload should show each file part with its binary content, not just a filename string

• Make sure the <script> tag is placed before the closing </body> tag.
• Check that the data-form attribute matches your form's link ID.
• Look for JavaScript errors in your browser's developer console (F12 → Console).
• Ad blockers or privacy extensions may block the widget script. Test in a private/incognito window.

The widget auto-closes 3 seconds after a successful submission. If it's not closing:

• The form may be redirecting to a custom URL — remove the redirect URL in Settings to use the default thank-you page.
• If using a custom redirect, the widget detects the URL change in the iframe. Cross-origin redirects may prevent this detection.

• Include the header: Authorization: Bearer fb_sk_your_key
• Make sure the full key was copied — it is only shown once when created.
• Check the key hasn't been deleted from the API Keys page.

Write access (POST, PATCH, DELETE) requires:

1. A Pro plan or higher
2. An API key with full scope (not read-only)

Personal plan users can only use GET requests. Upgrade to Pro for full API access.

After a FormBlade update, your browser may have cached the old JavaScript bundle. If you see a banner saying "A new version is available", click Reload page. You can also hard-refresh with Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).

Monthly limits reset on the 1st of each month at midnight UTC. The count is across all your forms combined.

• Personal: 300 submissions/month
• Pro: 3,000 submissions/month

Spam submissions count toward the limit because they were accepted before being flagged. Deleting submissions does not reduce the monthly count. Upgrade if you need more.