Last reviewed October 2024
Please give these debugging tips a try before making a new post. If none of the suggestions work, please include the requested information that we request at the end of this guide in a new post that you create. Thank you!
Why use Forms?
Forms are one of the most useful parts of modern websites because they allow us to capture input from our visitors.
There are many ways to use forms: such as contact forms and sign-up forms. Seeing as there are many types of forms, implementing one can take time. Here are some tried and true approaches to debugging common form errors and things to consider.
Form-handling works automatically for HTML forms that meet the following requirements:
-
You need to have a netlify or data-netlify=true attribute in your HTML <form …> definition. Note that once the form is processed during deploy, the resulting HTML that we serve will NOT have that parameter in it anymore!
-
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 HTML form includes a name. This name should be unique across a site.
-
Do not include extended symbols like @ in your <form ...> html definition. These will prevent our form detection from finding your form!
-
Apostrophes (') are a hard no in the attribute values of input tags. For example, value="Don't do this" would result in build errors. Instead use value="Do not do this".
-
Every input in the form must have a unique “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 our API will only record data from form submissions with names matching the definition as parsed at deploy time.
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:
Thank-you page
- 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 parameter in your form definition. (/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 to 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 use our own standard thank-you page.
If you’re using a pure javascript form or Server Side Rendering 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. This is required because we parse HTML to find forms during your deploy - but we don’t try to parse javascript files. This means if you are using any framework 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.
OK, did it work? Here’s some tips to tell, and a caveat:
HTML forms: Once the HTML form is deployed with the netlify attribute, 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 format. The form along with its detected fields will also be logged in the build log.
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.
Submits fine, yet no submissions in UI:
When you’re absolutely sure that the submissions are being sent correctly by the browser, but you’re not seeing them in the UI, there are 2 common scenarios that might cause this:
- The endpoint that you’re submitting to has a redirect. For example, if you’re using JavaScript to submit like:
fetch('/'... and you’ve a redirect rule like /* /foo 301!, submissions would probably not work. This is because the submissions are being “consumed” by the redirect rule. Instead, you cans set the endpoint to any other page that doesn’t redirect. Note: 200 rewrites could cause problems too.
- You’re using some kind of server side rendering to render the endpoint. For example, if you’re rendering the page that you’ve set as the endpoint using a serverless function, you’d not seem the submission in the UI. The solution is similar, set the endpoint to a page or an asset (like
/favicon.ico) that already exists.
- We use Akismet on all form submissions. If you see the form in the app.netlify.com UI, but you don’t see any of your test submissions, double check that you aren’t sending junk info in your test submissions or submitting over and over again from the same IP address (which looks spammy and may be hidden in our UI until you choose to view the spam submissions).
Are submissions being marked as spam?
Customers have reported that certain field names, such as from, can cause all submissions to be marked as spam. Double-check your form field names and consider renaming your fields – particularly if one is from!
Still having trouble? Please start a new topic tagged netlify-forms:
https://answers.netlify.com/tag/netlify-forms
In that topic, Please:
- Write a fantastic title that summarizes your issue and is helpful for other users
and provide:
- The URL for your live form as you want visitors to use it
- The URL of your deployed html form. In case you have a javascript form, we need to literally be linked to the html version you’ve deployed, as mentioned above (look for “pure javascript form”)
- The form name that you’ve set and that shows in our UI (if it shows in the UI)
- Any errors or logs from the Netlify build logs, dashboard or browser developer console
- Description of anything you have tried that did or didn’t help or make things better/worse
