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.

On this page:

• 404 Errors for freeform/plugin.js
• How do I transfer local dev changes to production?
• Emails not sending
• Form not submitting
• All Submissions Flagged as Spam
• 500 Error - No form ID specified OR The request response is empty
• Unable to verify your data submission
• Multiple emails being sent for Dynamic Recipients field
• Error when loading form in templates
• Error when deleting submissions
• Errors about missing files/pages in Freeform CP
• Javascript Errors in Safari when using reCAPTCHA
• Data not sending to API integrations
• Issues with Salesforce API connection
• How many sites can I use Freeform on?
• Does the Trial version limit Freeform features?
• How do I show textarea line breaks in email notifications or submissions?
• Submission data in fields showing HTML entities
• Can I parse basic HTML in field labels?

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

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:

• 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 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.
• 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.

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:

• 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 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:

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

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