Skip to main content

Troubleshooting Form Issues

This guide walks you through troubleshooting and diagnosing some of the most commonly reported issues with your form's appearance, behavior, or submission of the form on the front end.

​Instructions

1

​Check Freeform Diagnostics page

Some of the most common issues in Freeform are related to the following:

  • A newer version of Freeform resolves the issue. Please make sure you're using the latest version of Freeform, or at least check the Changelog to see if any relevant items have been fixed in newer versions.
  • The Freeform Script Insert Location setting is set to Manual. Most sites should use Page Footer, but in some cases it may be necessary to load these manually. If you must use Manual, please make sure you're loading Freeform's scripts in your forms with freeform.loadScripts(). Please see the guide in the JS Plugin documentation for more info.
  • There's an issue that Freeform has logged in the Error Logs. Freeform will sometimes log issues it discovers in its own error log file. Check out this area and see if there are any clues as to what might be causing the issue.
  • A custom module for Freeform is not working correctly or an unrelated module is interfering with Freeform.

If no relevant issues are found on the Diagnostics page, please proceed to step 2 below...

2

​Create a New Simple Template

Sometimes a quick and easy solution is to create a new template and add a basic Freeform form using the default Freeform sample template. This will help identify whether the issue is caused by errors in custom formatting templates, configuration issues, or other scripts that conflict with Freeform's.

This can alternatively be done by installing and using the Demo Templates that come with Freeform.

  1. Create a new template in your Craft /templates/ directory. Please ensure this is a blank template file, clean of any existing site layouts, scripts, etc.
  2. Copy and paste the following code into your new template, but replace yourFormHandle with the actual handle of your form:

    <html>
    <head></head>
    <body>

    {{ freeform.form("yourFormHandle", {
        formattingTemplate: 'basic-light/index.twig'
    }).render() }}

    </body>
    </html>

Some common template-level issues could be due to the following:

  • Your custom formatting template contains issues. The formattingTemplate: 'basic-light/index.twig' parameter in the above example will enforce Freeform's Basic Light formatting template, which could help determine if there are issues with your custom formatting template, if applicable.
  • Your template is missing a closing </body> tag. It is not enough to just paste the freeform.form query into a blank template. It needs to contain the closing </body> tag to know where to insert Freeform's scripts (if using the Page Footer option).
  • The form is being cached. Freeform is compatible with all kinds of caching, but please see the Caching guide to ensure you're following best practices.
3

​Load Your Form and Test

Go to the newly created template to load the form and see if everything works and behaves correctly.

  1. Does the form appear to display and behave correctly?
  2. Does the form submit correctly, without issue?
✅ Everything Works?

If the form displays and behaves correctly in this isolated test, it could be an issue with your custom formatting template or conflicts from other scripts with Freeform's scripts.

  • To troubleshoot this further, work in small steps. Stay inside the isolated test template and follow the steps below:
    1. Remove the formattingTemplate: 'basic-light/index.twig' parameter (thus pulling in your chosen and potentially problematic formatting template) from the Form query and see how the form displays and behaves.
    2. The isolated template may continue to display and behave incorrectly due to missing styles and assets. Try slowly pulling in some of those into the isolated test template and see if it breaks.
    3. If issues continue, compare your custom formatting template to existing formatting template examples included with Freeform.
    4. If you're still not getting anywhere, try creating a brand new custom formatting template based on one of the formatting template examples included with Freeform.
      • Load it in the isolated test template and confirm it works correctly.
      • Slowly modify it to become closer to your original custom formatting template, checking the isolated test template often along the way to see when/where it breaks.
      • This process will help you narrow down where the issue might be.
❌ Still Have Issues?

If issues are still occurring in this isolated test, there could be an issue with your Freeform settings, site or server configuration, or server rewrite rules.

  • Proceed to step 4 for diagnosing common issues...
4

​Check the Browser Console and Network Response

If the form still isn't loading or submitting correctly, check the browser's Console and see if any JS errors are logged. Also, check the Network tab for any issues. What you'll be looking for is the Response from a failed item.

  1. Click on the Network tab.
    • In the filters menu, select All to ensure all items are shown.
  2. Look for any items that are in red and click on them. In the case of the below example, the contact item was red.
  3. On the bottom-right side, click on the Response tab.
  4. The error will be logged here and will likely provide a clue as to where the issue might be. If you need assistance from the Solspace team, copy the error message there and create a new GitHub issue or private support ticket.

If the error does not show much detail, you may need to check the Craft logs OR consider temporarily enabling devMode for the site to see the error and stack trace.

5

​Contact Solspace Support

If you are unable to figure out the issue and need assistance from the Solspace team, please don't hesitate to create a new GitHub issue or private support ticket. and provide all relevant information you discovered while attempting to troubleshoot the issue.

See Support Options
Finished!
Page Feedback