[Common Issue] How to debug your form

Why use Forms?

Please give these debugging tips a try before posting a new post!
Forms are one of the most useful parts of modern websites because they allow us to capture input from our users.

There are many ways to use forms: contact forms, sign-up forms. Because forms can take many … uh… forms, implementing one can become tricky. Here are some tried and true approaches to debugging common form errors and things to consider. Comments are welcome!

Form-handling works automatically for HTML forms that meet the following additional requirements:

  1. You need to have a netlify or data-netlify=true attribute in your <form …> definition. Note that once the form is processed, the resulting HTML that we serve will NOT have that parameter in it anymore!
  2. You need to include a name attribute on the opening <form> tag. When the page is deployed we will add a hidden input with a form-name attribute that’s the same as the name you set for the form. This is used in our API to determine which form is receiving the input. This is handled automatically as long as the form includes a name.
  3. The name in the opening <form> tag needs to be unique on your site.
  4. Every input in the form must have a “name” attribute. Something like <input name="email" ...> or <textarea name="message" ...> is what you need. The name is sent along with the value in the submission and let’s our API know how to handle form submissions.
  5. The name in each of your <input> tags needs to be unique in that form.
  6. Make sure that you POST your form request (not GET) with a Content-Type of application/x-www-form-urlencoded. However, if you are submitting the form with a file upload then the Content-Type needs to be multipart/form-data
  7. We use Akismet on all form submissions. If you see the form in the app.netlify.com UI, but you don’t see any submissions, double check that you aren’t sending junk info in your test submissions.

If you have an HTML5 compliant form that follows those guidelines, it just works!

There are some things you’ll probably want to adjust to suit your tastes:

  • if you want to show your own content after the POST rather than our generic thank-you page, make sure you include an “action=/path” (/path should be the page you want to display - might be “/” or “/thank-you/english.html” - must be either ‘thank-you’ to use our automatic thank you page, or a path starting with / - but NOT a complete URL starting with http(s) ). While you wouldn’t seem to need an action for AJAX forms - it’s how we know what show after submission, so you do need one unless you’d like us to show our thank-you page. If this path doesn’t exist, we will also use our own standard thank you page.

If you’re using a pure-javascript form instead, this additional step is required:

  • You still need to include an HTML form that meets the criteria above, including all the inputs with the same names as the javascript form. Essentially, this is because we parse HTML to find forms during your deploy but not Javascript files. This means if you are using React, Vue, etc. which create HTML elements using Javascript during the render, you’ll still need to include an actual HTML file that includes all of the form details in it, including all possible inputs that you want to use.

For a working example using react that you can generalize to other frameworks from, check out this blog post from a co-worker: https://www.netlify.com/blog/2017/07/20/how-to-integrate-netlifys-form-handling-in-a-react-app/

OK, did it work? Here’s some tips to tell, and a caveat:

HTML forms: Once the HTML form is deployed with the netlifyattribute, you’ll see an entry (with its name from step 3) in our UI at https://app.netlify.com/sites/YOURSITENAME/forms . This will be present in our UI immediately after deploying. If it isn’t, we haven’t processed the form for some reason such as it not being present in HTML form.

Netlify Recaptcha: If you’re using the <div netlify-recaptcha></div> element to add our recaptcha, you can only have one on any single page. If you put this div in multiple places, only the first one parsed will be replaced with an actual recaptcha.

Still having trouble? Start a new post following the tips at the bottom of this thread



I think I may have found an additional failure mode we could cover here. I have a new site, with a form that shows up in the forms list, and seems to post successfully. It redirects to the default success page “Your form submission has been received.”, but I never see any submissions for the form in the dashboard and the email address registered for notifications never receives the submission.

Could this be because the site is still just a random-name-12345.netlify.com site? Do forms only begin working once you attach a domain name and setup SSL?


nope - forms work at any URL, so that isn’t the cause. Two most likely reasons for missing submissions which are both summarized as “It is most likely that they were marked as spam”.

  • 1 way that can happen is if you have set up some explicit spam prevention as documented here: https://www.netlify.com/docs/form-handling/#spam-filtering , but you are not using it correctly. Honeypot field filled out, or recaptcha not correctly configured. If either of those happen, the entry will be marked as spam regardless of content.
  • could be Akismet marking things as spam. This is likely in case you’ve tested a whole lot from the same IP address, or put real garbage data in, such as email address = test123.

Regardless, we’re working to release (code is mostly written, so this isn’t just “hope” but “bits committed already”) a UI for you to examine and mark entries as non-spam. For now, you’ll need to let us know what site it’s for and we can examine the missing entries in the database and mark them as non-spam for you, which will expose them to you for download/review.


Great information, thanks! After the first couple of tries, I did test with typical test data (e.g 111 Test Dr., me@example.com) sort of thing. But I never saw those first tries either, so there may be some other issue as well with my syntax or usage.

Here’s the site: [removed to comply with new user constraints.]

I’ve also opened a question on StackOverflow, so I’ll update it once I’m sure of the solution. It may be helpful to add this issue to the documentation with a recommended way of testing forms and a warning about obvious test data. Or maybe that will just be part of the documentation for the new feature you mentioned when it comes out.

EDIT WITH SOLUTION: It turns out my core issue was a duplicate name on a form input. This caused the initial issue, and I bet I spam blocked myself trying to troubleshoot. Here’s the Stack Overflow question with details.

Hello! I am working on building my first form for client’s site, and hopefully my site next. I’m using Gatsby and I’ve gone over the excellent documentation on this site and Gatsby guru codebushi. My submissions are going through, but they are blank. I have added name parameters to my inputs. I have tried changing the name of the form, but no new forms show up in Netlify. What else could I be doing wrong?
Thanks in advance for the help

Looking in Netlify’s database to find a form for your site with the same name as the one you linked, I see a definition for your contact form that has ONLY the bot-field in it - we didn’t process any other fields at deploy time.

Two likely possibilities:

  • For your site, since I can see that the html for that page does have <input ... name="name" ...> type fields (rather than building them via javascript), so perhaps you have a SECOND, empty definition of that form somewhere else in your source code? We’re looking for another <form name=contact ...> type definition. It is also the case that the last deploy on ANY branch will update the form definition for ALL branches so you could also have an empty form with that name in some testing deploy that has overwritten production. Forms work on any branch/preview URL, but the definition in use on all of them will be the MOST RECENTLY DEPLOYED one.

  • For others, whose forms are javascript-generated, it’s likely that you’re missing this (from the debugging steps):

  • You need to create an html form to match the JS definition exactly (same form name, field names, etc). New JS forms will ONLY appear in our UI and only be processed correctly from the browser, if you have deployed this html form. You do NOT have to link to it - you can just create a “netlifyneedsthis.html” file with those definitions in it (and deploy it with your site) and that will work!

As I mentioned that second one is not your problem @RJGrunau :slight_smile:

1 Like

Hi there - I’m trying to get a basic form set up using Netlify at https://reclaimapp.io/signup/. I’ve read through this thread, read the docs, and also checked out the example form on GH. The form appears correctly and routes to /thanks, but the submissions haven’t come through. Would love to know what I’m doing wrong. Thx!

Never mind! I forgot to add the “hidden” input to my JS file. It now works like a charm. So cool and nifty. Thanks for making great documentation (even if I don’t read it carefully enough).

1 Like

A post was split to a new topic: Required fields in forms?

I’m late and I apologize, but I wanted to follow up. The problem was me, I followed a tutorial instead of reading the docs. Got everything running perfectly. Thanks for your help.

1 Like

In case anyone runs into the problem I had:

I was having the same issue many of you ha{d|ve} - forms were showing up on app.netlify, but submissions were blank. After trying all the fixes in the various places on the internet it still wasn’t working.

I finally realized my own submissions were being filtered by Netlify’s spam-filtering service provider. After reverse engineering the spam filter tests through trial and error I found that if you have a form field named “twitter”, the spam filter Gods REALLY want (need) your entered data to start with an “@” character. Wow! Lost more than a day of my life to these spam filter Gods.

tl;dr - Make sure you enter good data while testing. For me that meant including “@” in my “twitter” field.

1 Like

I’ve got some news to share - the spam management UI that @fool mentioned earlier in this thread has now been released! Check out the blog announcement and updated Forms documentation to learn more. The docs now also include tips on how to avoid having your test submissions flagged as spam in the first place.

1 Like

check this post :point_right: Manage spam submissions is now available in the UI!

1 Like

Hi there,

I have been struggling to setup a form on my VueJS site. I’ve tried many different variations and am still unable to receive form submissions. It redirects to a 404 each time the form has been submitted.

<form name="contact" method="POST" class="contact__form" netlify-honeypot="bot-field" data-netlify="true">
  <input type="hidden" name="form-name" value="Contact" />
    <p style="display: none" class="hidden">
     <label>Don’t fill this out if you're human: <input name="bot-field" /></label>
  <div class="contact__row">

    <div class="contact__col">
     <input v-model="form.name" name="name" type="text" placeholder="Your Name" class="contact__input contact__input--name">
    <div class="contact__col">
     <input v-model="form.email" name="email" type="email" placeholder="Email Address" class="contact__input contact__input--email">
  <div class="contact__row">
    <div class="contact__col">
      <textarea v-model="form.message" name="message" class="contact__textarea contact__input" cols="50" rows="10"></textarea>
  <div class="contact__row">
    <div class="contact__col contact__col--right">
      <button type="submit" class="contact__button">Send</button>

Is it possible and if, how do you remove IP addresses of form submitter?

Hi there,

You can remove the form submissions from our system; that is the only way to remove the IP address information from our storage at present.

Hi Spencer!

Did you follow the steps in the original post at the top of this thread? 404 usually means one of a few things:

  1. Perhaps, we never recognized your form. When you show the form html - where is that stored? In a literal .html file, or is it built from JS dynamically? Do you see the form in the site config dashboard? (I see a form there with that name, but the last submission was rather after you posted in this thread, so maybe things have changed?
  2. You submit to an unexpected path. Based on that HTML, we’d only be looking for a POST to / since you have configured no explicit action=
  3. You submit with an unexpected form-name. This is/was likely the problem - “contact” != “Contact” and you have them mixed in your definition:
<form name="contact" method="POST" class="contact__form" netlify-honeypot="bot-field" data-netlify="true">
  <input type="hidden" name="form-name" value="Contact" />

Do form submissions work on a site’s Default Subdomain?

Or do they only work on the site’s Primary Domain?


Forms are not dependent on specific domains at all, @emb. They will work on your netlify subdomain, custom domains domain aliases, etc.