Skip to main content

Common Issues & Questions

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

On this page:

404 Errors for freeform/plugin.js

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

Answer

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 URLs 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

If you're wondering how to independently carry over changes/additions 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, elements_sites, and content database tables. Freeform forms are stored as JSON in the freeform_forms database table, but the fields within are also attached to the freeform_fields and freeform_submissions database tables, complicating it further. And finally, if form data and layouts were stored inside the Craft 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.

A future version of Freeform will eventually include an import/export utility that will solve this issue.

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:

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:

All Submissions 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:

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.

Multiple emails being sent for Dynamic Recipients field

When using the Dynamic Recipients field type, I sometimes am receiving duplicate email notifications when the form is submitted.

Answer

This is likely because you've specified more than one option with the same email address value. This is a current limitation of Freeform, as Freeform will perceive the user submitting all of the matching options at once, sending off emails as many times as there are duplicate options.

There are a few workaround for this:

  1. Create an email address alias for each option so that each option in the Dynamic Recipients field type settings will be unique.
  2. Add sub-address tags to the affected email addresses so their values are unique. For example: joe+whatever@example.com, joe+somethingelse@example.com, etc.
  3. Build a custom module that sends an email notification to a recipient based upon the selection of a Select/Checkbox Group/Radio fields' option using the EVENT_AFTER_SUBMIT event. We've created a guide that will get you 99% of the way there.

A future version of Freeform (v5) will resolve this issue entirely.

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:

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 CP

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:

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 many sites can I use Freeform on?

Answer

Each license purchase of Freeform entitles you to use it on one site, which includes all dev/staging versions of the site as well - these do NOT require additional licenses. For any additional separate site you wish to use Freeform on, you'll need to purchase an additional license.

Does the Trial version limit Freeform features?

Answer

The trial versions of Solspace plugins are not limited in any way. They are the complete versions, and let you do the same things as a purchased license. However, if you attempt to use a trial version on a production site, Craft will display a red banner at the top of your control panel alerting you to purchase a license.

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 }}

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({
labelClass: (field.required ? " required" : ""),
instructionsClass: "help-block",
errorClass: "help-block",
}) }}

{% 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 %}