Common Issues & Questions

Check out this documentation resource to troubleshoot common problems or find answers to common questions.

Quick troubleshooting the most commonly reported issues with your form's appearance, behavior, or submission of the form on the front end.

Emails not sending

How come email notifications are not sending out when a form is submitted?

Answer

The most common issue users run into is email notifications not sending out properly. Most commonly, this is due to a syntax error in their notification template, or an email server configuration issue. Here's a checklist to go through and see if any of them might be at play:

• Are you 100% certain the email notification is not in a spam folder?
• Is the email address correct?
• Is the form successfully being submitted? You can verify this by checking for submissions in the Freeform control panel. If you have the Store Submitted Data setting disabled for the form, consider enabling it temporarily to confirm this.
• Have you checked the Freeform Error Log page (Freeform → Settings → Error Log)? The Freeform error log is physically located in the same place as the Craft logs (/storage/logs/freeform.log). If there are no logged errors, the Error Log page will not show any errors, and you will likely not see the Freeform error log file.
• Are you using SMTP or a service that uses SMTP (like Sendgrid, etc)? If so, please make sure that the email address you have configured in the From Email setting for the email notification exactly matches what you have set in the Craft Email Settings area. If you wish to use the submitters email address as the "From" email, use the Reply-to Email setting instead.
• Have you assigned an email notification template to the Email field, User Select field, or admin Notify area inside the form builder for the given form? For all types of email notifications, they are assigned to fields or the form itself inside the Property Editor column (right side) in the form builder.
• If using the dynamicNotification parameter at template level, be sure to have the proper syntax and the proper email notification template name (with .html file extension if using HTML file).
• Verify that your email notification template is using the correct syntax. Using incorrect syntax will result in a silent error and failure of the email notification sending. For all inputs such as Subject and From Name, as well as the Email Body area, the syntax is as follows:
  • All custom Freeform fields are {{ fieldName }}
    • E.g. {{ firstName }}, {{ email }}
    • Do not prefix the properties with form., as that refers to info about the form itself (see below)...
  • Anything related to info about the form itself is as follows:
    • {{ form.name }} - the Name of the form
    • {{ form.handle }} - the Handle for the form
    • {{ form.id }} - the ID of the form
• Verify that the fields you're manually calling (if applicable) actually exist for the form and contain data. For example, if you include a field such as {{ fullName }} in the From Name input field, but your form uses something like {{ firstName }} and {{ lastName }} instead, it will result in a silent error and failure of the email notification sending.
• If using HTML files for your email notification templates, verify that your Directory Path setting is correct. This can be a common issue if you're switching between dev/staging/production environments.
• Have you tried testing this inside the demo templates that come included with Freeform? This will at least help narrow things down to possibly an error in your template code if applicable.
• Are you sending to and from the same email address or email address domain? For example, sending FROM bob@my-precio.us TO bob@my-precio.us, OR FROM bob@my-precio.us TO larry@my-precio.us. Sometimes the email server has very aggressive spam protection and knows that the email is not actually coming from that email address, and blocks the email altogether.
• Can you send email with Craft's Email Testing feature? Freeform uses Craft's Email service, so if that doesn't work, then Freeform won't either. To check this, in the Control Panel go to Settings → Email, then scroll down to the bottom of the page and click the Test button. You can read more about troubleshooting email errors on Craft's documentation page.
• To be extra thorough, you can also try sending notifications with Craft's simple Contact Form plugin.
• Are you getting redirected correctly after form submission? Be sure that you don't have any routes or .htaccess rewrites that conflict with the form submission.

Form not submitting

When I submit my form, it errors unexpectedly or doesn't do anything.

Answer

A common issue customers run into is their forms not submitting successfully. There's a variety of reasons this might be. Here's a checklist to go through and see if any of them might be at play:

• Are you sure the form is not being successfully submitted? You can verify this by checking for submissions in the Freeform control panel. If you have the Store Submitted Data setting disabled for the form, consider enabling it temporarily to confirm this.
• Have you checked the Freeform Error Log page (Freeform → Settings → Error Log)? The Freeform error log is physically located in the same place as the Craft logs (/storage/logs/freeform.log). If there are no logged errors, the Error Log page will not show any errors, and you will likely not see the Freeform error log file.
• Have you tried testing this inside the demo templates that come included with Freeform? This will at least help narrow things down to possibly an error in your template code if applicable. If your form doesn't work inside the demo templates, try creating an additional form that is simple (e.g. Name, Email, and Message fields), and try submitting again.
• Do you have caching on your template and/or site? Heavy caching will prevent the Craft CSRF token and Freeform hash from reloading and stop the form from working. If you need to cache your page/site, you'll need to find a way to manually refresh these for each page load.
• Do you have a rewrite rule for trailing slashes to be removed for .htaccess or Nginx? Try temporarily removing or disabling that and see if it resolves the issue. If using Nginx, you may want to check out this article.
• Do you have Javascript enabled for your browser? If you don't, and you're using Freeform's built-in Javascript Test feature, it won't submit the form successfully.
• Is the form part of an entry and/or page that is generated by a disabled Craft entry (URL includes token like ?token=ay2ZFhCPSSvNLLjWxV1QnxO823JjHB-z)? Freeform forms will be blocked from working on pages that are disabled this way.
• Have a look at the Blocked Spam count for your form in the CP → Freeform → **Forms** list. If the count is increasing each time you attempt to submit the form, Freeform's Spam Protection feature is blocking your submissions.
• Try disabling the Spam Honeypot feature ( CP → Freeform → Settings → Spam Settings and set Spam Protection setting to disabled) and test again.
• Are you getting redirected correctly after form submission? Be sure that you don't have any routes or .htaccess rewrites that conflict with the form submission.
• To be extra thorough, you can also try submitting Craft's simple Contact Form plugin.

All submissions are being flagged as spam

All of my submissions are being flagged or blocked as spam.

Answer

If all of your form submissions are being blocked as spam or appearing in your Freeform control panel Spam Folder, try going through the following checklist:

• Have you tried testing this inside the demo templates that come included with Freeform? This will at least help narrow things down to possibly an error in your template code if applicable. If your form doesn't work inside the demo templates, try creating an additional form that is simple (e.g. Name, Email, and Message fields), and try submitting again.
• Do you have caching on your template and/or site? Heavy caching will prevent the Craft CSRF token and Freeform hash from reloading and stop the form from working. If you need to cache your page/site, you'll need to find a way to manually refresh these for each page load.
• Do you have a rewrite rule for trailing slashes to be removed for .htaccess or Nginx? Try temporarily removing or disabling that and see if it resolves the issue. If using Nginx, you may want to check out this article.

404 Errors for 'freeform/plugin.js'

Some fields and other JS in my form are not working correctly. I'm also seeing this error in the browser console: freeform/plugin.js net::ERR_ABORTED 404 (Not Found).

Freeform 5.3+

Answer

It's possible this could be a caching issue. First try clearing your Craft cache and see if that helps.

If you're using Freeform 5.3+, this issue is very unlikely to occur. The Freeform Script Insert Type setting was improved and no longer offers the Static URLs option, which was likely to cause this issue in some environments.

Freeform 5.0.x to 5.2.x

Answer

It's possible this could be a caching issue. First try clearing your Craft cache and see if that helps.

If the JS in your form is not working and you're seeing an error like freeform/plugin.js net::ERR_ABORTED 404 (Not Found) in the browser console, it's almost certainly due to your site having server rules you have applied to JS and CSS files to see if they are actual files. The default for Freeform is to load its scripts as Static URLs, which becomes a problem in this case. To resolve this issue, you can switch the Freeform Script Insert Type setting (Craft CP → Freeform → Settings → Form Behavior) to As Files instead.

• As Static URLsRecommended offers built-in browser caching and a static endpoint that delivers the latest Freeform scripts, but are not physical files and therefore cannot have server rules applied.
• As Files (recommended if having issues with Static URLs) are actual physical files generated inside of the cpresources folder by Craft's asset manager with no caching.
• Inline will add the scripts as inline scripts and may be useful as a workaround if the other 2 options are not working. This doesn't allow for caching, and pollutes the source code.

If you're experiencing this issue only in one environment (like production), it's perfectly safe to just set all environments to use As Files without issue.

How do I transfer local 'dev' changes to 'production'?

I have a made a number of updates and changes to my Freeform setup on my local dev environment. I'd like to move that over to the staging/production environments. Is this possible?

Answer

The best way to go about this is using Freeform 5's new Import / Export feature. It allows you to granularly import and export partial or entire Freeform setups from one site or environment to another. This could be used for performing site updates across environments and syncing changes in Freeform, or as a boilerplate for new sites.

Further reading...

If you're wondering if you can manually carry over changes/additions in the database to forms, fields, submissions, etc from one environment to another, this is not currently possible. The issue is that Freeform submissions are technically Craft elements and therefore, things are intertwined within the Craft elements and elements_sites database tables. Freeform forms are stored as JSON in the freeform_forms and various other freeform_forms_* database tables, but the fields within are also attached to the freeform_submissions_* database tables, complicating it further.

Additionally, if form data and layouts were stored inside Craft's project config, it would mean that forms could not be created and edited on sites that use the allowAdminChanges setting in Craft. This might work for some customers, but definitely not everyone. This is why we built the new Import / Export feature as mentioned above.

500 Error - No form ID specified OR The request response is empty

When trying to save my form in the form builder, I get a No form ID specified OR The request response is empty error.

Answer

If you're seeing either of these errors or something similar when trying to save your form in the CP form builder or submit the form in front end template, it's very likely related to your site having a rewrite rule for trailing slashes to be added or removed for .htaccess or Nginx. Try temporarily removing or disabling that and see if it resolves the issue. If using Nginx, you may want to check out this article.

The easiest way around this might be to just try excluding the admin directory from the rewrite:

.htaccess

# Append a trailing slash
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !/$
# Exclude Admin directory
RewriteCond %{REQUEST_URI} !^/admin/
RewriteRule . %{REQUEST_URI}/ [R=301,L]

Nginx

# Redirect URLs with trailing slash, exclude Admin directory
rewrite ^/(?!admin)(.*)/$ /$1 permanent;

Also be sure that you don't have any agressive security settings enabled on your server such as ModSecurity / SQL injection detection.

Unable to verify your data submission

When submitting my forms, I am getting an Unable to verify your data submission error.

Answer

This is almost always because Craft's CSRF token is invalid or expired. The most common causes of this are:

• Form/template/website is cached - if using cache, please see the Caching Forms documentation guide to see how you will need to manually refresh the Craft CSRF token.
• Browser left open too long - if the user leaves the page open for a while and revisits later, or spends too much time to complete the form (2-3 hours), the Craft CSRF token will expire. This is a limitation of the current PHP Session limit setting for your server. You may be able to extend it for a greater length of time if you contact your webhost/web admin, however.
• Loading Freeform onto a different website/domain - this should work by default, but if you have the sameSiteCookieValue Craft config setting set to strict or lax, it may cause an issue. You'll need to remove the setting line or set it to null in order for it to work correctly.

Error when loading form in templates

I am getting an error when trying to load a form in my template. It looks like this:

Solspace\Freeform\Library\Exceptions\FreeformException: Form template 'some-template.html' not found in /PATH/freeform/src/Services/FormsService.php:343

Answer

This is very likely because you assigned a custom Formatting Template to your form, and then at some point did one of the following:

• Renamed the formatting template file.
• Deleted the formatting template file.
• Specified an incorrect Formatting Template directory path in your settings.
• Switched environments and the Formatting Template directory path setting is incorrect.

To correct this issue, ensure that:

• The path to your Formatting Templates directory path is correct.
• The formatting template the form was assigned (at some point) exists.

If you want to change the name of the formatting template file while it is already in use for form(s), you should:

1. Assign the form(s) a different formatting template
2. Rename the original formatting template file (when no forms are using it)
3. Reassign the newly renamed formatting template to the form(s) it should belong to.

Error when deleting submissions

I am getting an error like Class 'Freeform_Submission' not found while trying to delete submissions in the control panel.

Answer

This is very likely due to a migration from Freeform for Craft 2 missing this part on old submissions. This will need to be resolved manually by updating all instances of Freeform_Submission (Craft 2 style) in the type column of your Craft elements database to Solspace\Freeform\Elements\Submission (Craft 3+ style). Be sure to back up your database first.

Errors about missing files/pages in Freeform control panel

I'm seeing an error in the Freeform control panel area saying that a file or page doesn't exist / is missing, (e.g. when attempting to create a new email notification template, etc).

Answer

This is usually a result of the file actually being missing on the site, or being blocked for some reason. Make sure that your server, site, or FTP client is not ignoring or excluding certain files and/or directories for any reason (e.g. an .htaccess rewrite rule that manipulates URL's can interfere with Freeform's POST to /save by redirecting it to /save/, etc). In all known cases of this, the aforementioned solutions always resolved the issue. Also be sure that you don't have any agressive security settings enabled on your server such as ModSecurity / SQL injection detection.

Javascript errors in Safari when using reCAPTCHA

I'm seeing JS errors that say "The source list for Content Security Policy directive 'script-src' contains an invalid source: "strict-dynamic". It will be ignored. on forms using reCAPTCHA in Safari.

Answer

This is out of our control as it is a known issue with Google and Safari. It technically does not interfere with the form functioning correctly, but they are choosing not to address the issue for some reason.

Data not sending to API integrations

My submission data is not being sent to the API integration I have selected and mapped out.

Answer

The most common reason why data doesn't get sent to an API integration is because of a field mapping error, whether it's a required field on the API integration side that isn't being fulfilled on the Freeform submission, or the data formatting not matching expectations, etc. Try going through the following checklist:

• Have you checked the Freeform Error Log page (Freeform → Settings → Error Log)? The Freeform error log is physically located in the same place as the Craft logs (/storage/logs/freeform.log). If there are no logged errors, the Error Log page will not show any errors, and you will likely not see the Freeform error log file.
• Have you tried testing this inside the demo templates that come included with Freeform? This will at least help narrow things down to possibly an error in your template code if applicable. If your form doesn't work inside the demo templates, try creating an additional form that is simple (e.g. Name, Email, and Message fields), and try submitting again.
• Is the field type / data formatting supported in the API integration? Not all field types are supported for each integration. This is usually noted near the top of the page of each API integration setup documentation page.

Issues with Salesforce API connection

I am seeing errors displayed or logged in the Freeform error log for my Salesforce integration.

Answer

One reason is that Salesforce usually disables the API access entirely with their Trial version. If you're using the Trial version, you will need to contact Salesforce support to manually enable it for you.

If you're seeing any errors as follows:

Client error response [status code] 400 [reason phrase] Bad Request [url] https://login.salesforce.com/services/oauth2/token'

• This is because Salesforce runs differently when in Sandbox mode, so be sure to enable the Sandbox Mode option inside the CRM integration setting in the Freeform control panel.

No 'refresh_token' present in auth response for SalesforceLead. Enable offline-access for your app.

• Make sure that the Perform requests on your behalf at any time (refresh_token, offline_access) setting is added to the Selected OAuth Scopes field for your app in Salesforce.

How do I show textarea line breaks in email notifications or submissions?

Answer

Textarea data is stored in the database as newlines, which obviously don't parse as line breaks when trying to display in email notifications or on front end with Submissions object. To make this happen, use the nl2br Twig filter:

{{ myFieldHandle|nl2br }}

Submission data in fields showing HTML entities

When rendering submission data in email notifications or the front end, several characters such as ' are parsing as ', e.g. You're a wizard Harry!.

Answer

In rare circumstances, some customers have reported this issue happening. A solution for this would be adding the |raw filter to the field property, or wrapping {% autoescape false %} around it:

{{ message.value|raw }}

OR

{% autoescape false %}
  {{ message.value }}​
{% endautoescape %}

Can I parse basic HTML in field labels?

Answer

If you like, you can enter basic HTML into field labels and option labels while inside the form builder. This is especially handy if you want to add emphasis to an option or add a link to an option (e.g. link a checkbox label for Terms & Conditions page).

The demo and sample templates will likely handle the HTML in the form rendering automatically, but in cases where it doesn't, you may need to apply the raw Twig filter:

Getting HTML (b, i, etc) to parse for field option labels:

{{ field.renderLabel() }}

{% for option in field.options %}
  <div class="checkbox">
    <label>
      <input type="checkbox" name="{{ field.handle }}[]" value="{{ option.value }}" {{ option.value in field.value ? "checked" : "" }} />
      {{ option.label|raw }}
    </label>
  </div>
{% endfor %}

Can I test Freeform before I buy?

Answer

Yes! You can use Freeform on any private domain name for as long as you need, just like with Craft. Whether it's on your local dev server or a staging site, you're good to go. You only have to buy a license when you're ready to launch your site live, just like with Craft.

How many sites does a license cover?

Answer

You only need to buy a Freeform license for each Craft license you have. So, if you're running a Craft multi-site on one install, you just need one license. It's just like Craft! There's no need to get separate licenses for other environments of the same site, like development or staging.

Can I switch to a different edition later?

Answer

Yes! You can switch to the Lite or Pro editions at any time! You just pay the difference in price. For example, if you're using the Lite edition and wish to switch to Pro, you will just pay $50. You don't need to reinstall anything and you won't lose any of your data.

Check out the Changing Editions guide for more information!

Do you offer discounts to non-profits?

Answer

Yes! We offer a discount to non-profits for 20% off the regular price upon proof of non-profit status. Please contact us for more information about this.

Does the Trial version limit features?

Answer

The trial versions of Solspace software are fully functional and not limited in any way. However, if you try to use a trial version on a production site, Craft will display a red banner at the top of your control panel, prompting you to purchase a license.

More information about Craft's license enforcement.

How long does a license last for?

Answer

A single license provides one year of updates and support. After this period, you can continue using the plugin but will no longer receive updates or support. To maintain access to updates and support, you will need to renew your license each year at a discounted rate.

Do I have to renew my license each year?

Answer

You can renew your license after the initial one-year support period has ended. Your plugin will continue to work properly in the meantime. If you prefer, you can wait until the following year to renew and receive the latest updates.

However, we don't recommend avoiding updates altogether, as you would miss out on new features and important fixes.

What are renewals and how do they work?

Answer

Renewals help you keep your plugin updated and access technical support. However, they are entirely optional.

For example, if you purchase the Lite edition of Freeform for $99, the renewal price after one year is $49. Your initial purchase of $99 includes support and updates for one year. When it's time to renew, you can extend your updates and support for another year at the renewal price of just $49, rather than paying the full amount of $99 again.

How do I install Freeform?

Answer

Installing Freeform is done just like any other plugin for Craft, similar to how you would install Craft itself. Please refer to the Installation guide in the documentation.

How do I get support for Freeform?

Answer

We provide free support for Freeform. If you have any questions or encounter issues, you can create an issue on GitHub or send us a private support ticket. We're here to help!