Common Issues & Questions
Check out this documentation resource to troubleshoot common problems or find answers to common questions.
- Emails not sending
- Incorrect Email Formatting
- Form not submitting
- Composer Form Builder is blank / not loading correctly
- Updated field options aren't showing
- Error about field when submitting form
- Certain uploaded files are not being accepted
- Form submits very slowly
- Error when loading form in templates
- Errors about missing files/pages in Freeform CP
- Javascript Errors in Safari when using reCAPTCHA
- "The request response is empty" error when saving a Form or "fatal error of ../freeform_next/vendor/symfony/polyfill-mbstring/Mbstring.php"
- Errors about Update Service
- Data not sending to API integrations
- Issues with Salesforce API connection
- How many sites can I use Freeform on?
- If I switch from Classic to the new Freeform version ("Next"), will all of my data move over with it too?
- Can I run Freeform Classic and the new Freeform version ("Next") at the same time?
- What kind of email notifications can I send?
- How many fields can I have?
- Can I show POST data on the success page?
- How do I return form submit to same page with success message?
On this page
- Emails not sending
- Incorrect Email Formatting
- Form not submitting
- Composer Form Builder is blank / not loading correctly
- Updated field options aren't showing
- Error about field when submitting form
- Certain uploaded files are not being accepted
- Form submits very slowly
- Error when loading form in templates
- Errors about missing files/pages in Freeform CP
- Javascript Errors in Safari when using reCAPTCHA
- "The request response is empty" error when saving a Form or "fatal error of ../freeform_next/vendor/symfony/polyfill-mbstring/Mbstring.php"
- Errors about Update Service
- Data not sending to API integrations
- Issues with Salesforce API connection
- How many sites can I use Freeform on?
- If I switch from Classic to the new Freeform version ("Next"), will all of my data move over with it too?
- Can I run Freeform Classic and the new Freeform version ("Next") at the same time?
- What kind of email notifications can I send?
- How many fields can I have?
- Can I show POST data on the success page?
- How do I return form submit to same page with success message?
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:
Incorrect Email Formatting
Why do my email notifications appear broken with spaces and extra characters inserted into the message?
Answer
This issue usually appears when using Office 365 to handle email notification processing. The problem is not specific to Freeform but is more of an EE issue.
The only known solution is to edit the core EE file at ee/legacy/libraries/email.php
and change line 169 to public $crlf = "\r\n";
. Changing the new line character in EE's Outgoing Email Settings does not fix this, but the above will.
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:
Composer Form Builder is blank / not loading correctly
When attempting to view my form in the form builder, I get a blank page or it isn't loading correctly.
Answer
If the Composer interface inside the Freeform control panel is not loading correctly, it's very likely to do with the Freeform themes folder missing / being old / being corrupt. Remove the freeform_next themes folder and try uploading it again. It may also be an issue with folder/file permissions. Please make sure the correct permissions are set as well.
Updated field options aren't showing
When I update a field's options or settings inside the Field Manager area, those changes aren't reflected on my existing forms in the form builder.
Answer
Freeform takes a bit of a unique - but flexible - approach to fields. Fields are global and available to all forms, but they can also be overwritten per form. This allows you to save time reusing existing fields when making other forms, but also gives you flexibility to make adjustments to them when needed. So to clarify, you can create fields with labels and options that are common to all forms, but also override those on each form. For example, if you have a field named Cell Phone, on the form level, you can rename the field name to Mobile Phone, or if you have a Checkbox Group field with options: Option A, Option B, and Option C, you could override it to just have 2 options with values of Option A and Option B, and/or add Option D.
The possibly confusing part here is that when you edit/add/remove options at Composer level for each form, they will NOT update the "master" field options/labels. And likewise, if you edit/add/remove options at the "master" field level (Freeform -> Fields), they will NOT update any existing usage of this field in the forms they're assigned to. It would be chaos if it did in either case, and prevent you from being able to tweak field labels and options per form.
If you plan on building several forms with matching fields (that have matching options, etc), we strongly encourage you to create the field(s) in main Field area (Freeform -> Fields) first with all the options you'd like. Then when you construct your forms, you'll see all the default options available. It's better to think of the main fields area as defaults for new forms (or new assignments of that field to existing forms).
Error about field when submitting form
When submitting the form, I get an error about an unknown field column.
Answer
If you're receiving an error when submitting a form or when creating a new field (such as SQLSTATE[42S22]: Column not found: 1054 Unknown column 'field_112' in 'field list':
), it's likely because you've reached the maximum number of fields for your site unfortunately. There is currently a limit on the number of Freeform fields for each install of ExpressionEngine (around 85-125), due to the MySQL column limit, since all fields are stored in a single table. The total limit is also dependent on the type of fields you have, your server setup and encoding type, etc. The reason this error occurs is because the field gets added as a row to the freeform_next_fields
database table, but there isn't room to add the field as a column in the freeform_next_submissions
database table.
The good news is that fields are global and available to all forms, and can also be overwritten per form. This allows you to save time reusing existing fields when making other forms, but also gives you flexibility to make adjustments to them when needed. So to clarify, you can create fields with labels and options that are common to all forms, but also override those on each form. For example, if you have a field named Cell Phone, on the form level, you can rename the field name to Mobile Phone, or if you have a Checkbox Group field with options: Option 1, Option 2, and Option 3, you could override it to just have 2 options with values of Option A and Option B.
If you're building survey forms for example, you might want to create a dozen or so generic fields of each field type you commonly use, and just rename them for each survey form.
Certain uploaded files are not being accepted
When attempting to upload some files to my file upload field, I get an error about an unknown or disallowed file type.
Answer
If you have a form that doesn't seem to be accepting files such as docx
or similar, it could be a variety of issues ranging from which application compiled the file to your server configuration. One possible workaround to this would be adding the Mime Whitelist Additions rule to your EE config file (e.g. docx
):
$config['mime_whitelist_additions'] = array(
'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
);
2
3
You may also need an .htaccess directive (added to top of the file before any rewrite rules):
#mimetype addition docx
AddType application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx
2
Form submits very slowly
I'm noticing that it takes a long time to submit my forms sometimes.
Answer
If you're experiencing performance issues with Freeform, it could be due to a variety and combination of reasons. If forms are taking a long time to submit, consider the following options, and create a support ticket with the info below if necessary:
Error when loading form in templates
I'm getting an error about a form template not found when trying to view my form on the front end.
Answer
If you're getting an error that looks something like this:
Exception Caught
Form template 'some-template.html' not found
user/addons/freeform_next/Services/FormsService.php:65
2
3
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 the path to your Formatting Templates directory path is correct, and that the formatting template the form was assigned (at some point) exists.
TIP
If you want to change the name of the formatting template file while it already is in use for form(s), you should first assign all other form(s) another formatting template, then rename the formatting template file, and then reassign the form(s) to that newly renamed formatting template.
Errors about missing files/pages in Freeform CP
I'm getting an error saying a page or file doesn't exist / is missing when using the control panel.
Answer
Customers will sometimes see errors 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). 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.
Javascript Errors in Safari when using reCAPTCHA
I'm getting getting 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 a known issue on Google and Safari's part. It technically does not interfere with the form functioning correctly, but they are choosing not to address the issue for some reason.
"The request response is empty" error when saving a Form or "fatal error of ../freeform_next/vendor/symfony/polyfill-mbstring/Mbstring.php"
I'm seeing the error The request response is empty or fatal error of ../freeform_next/vendor/symfony/polyfill-mbstring/Mbstring.php when attempting to save my form inside the Freeform CP Composer page.
Answer
This error is likely due to your server not having PHP iconv enabled. The Freeform dependency symfony/polyfill-mbstring requires it. It's not very common that a server does not have iconv, but does happen.
Errors about Update Service
I'm seeing errors referencing the Freeform Update Service in the control panel.
Answer
If you're seeing errors referencing the Freeform Update Service, it might just be a temporary glitch. To resolve this issue right away, delete the freeform_next folder in the /system/user/cache/
directory, which would let Freeform try downloading the Changelog again.
Data not sending to API integrations
I have set up an API integration with my form but the submission data isn't sending to it.
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.
Issues with Salesforce API connection
I am seeing errors about Salesforce in my error log.
Answer
Salesforce usually disables the API access entirely with their 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 purchase of Freeform entitles you to use it on one site (including dev/staging copies of the site). For every additional site you wish to use it on, you'll need to purchase additional licenses.
If I switch from Classic to the new Freeform version ("Next"), will all of my data move over with it too?
Answer
The new Freeform was completely rebuilt from scratch, and while it of course contains much of the same functionality as Freeform Classic, it's actually a whole new add-on. Because of this, along with the drastic changes we made in the architecture of "Next", there currently is no migration path. We are however in the process of making a migration path that will be available in the not-to-distant future. In the meantime, because the new Freeform has a different module name and the add-on folder is named freeform_next
, it means that it won't conflict with classic Freeform installs in anyway. This allows you to explore and try the new Freeform out and/or transition from Freeform Classic to "Next" at a comfortable pace. You can even keep Freeform Classic around for legacy viewing of submissions too.
Can I run Freeform Classic and the new Freeform version ("Next") at the same time?
Answer
The simple answer is, YES! The longer answer is... the new Freeform has a different module name and the add-on folder is named freeform_next
. This means that it won't conflict with classic Freeform installs in anyway. This allows you to explore and try the new Freeform out and/or transition from Classic to "Next" at a comfortable pace. You can even keep Classic around for legacy viewing of submissions too (as there currently isn't a migration path from Classic to the new Freeform yet).
What kind of email notifications can I send?
Answer
Freeform allows you to send email notifications upon submittal of a form 5 different ways, each with their own content/template:
- To admin email address(es) for the form (set inside Notify area of Composer)
- To a predefined select menu/radios of email addresses (and labels) for the user to choose (Dynamic Recipients field type).
- To the user submitting the form, with the email addresses specified/selected in the Email field type.
- To a user-defined email address (e.g Tell-a-Friend form), with the email addresses specified/selected in the Email field type.
- At template level with the dynamic_notification_recipients parameter.
How many fields can I have?
Answer
There is currently a limitation of around 85-125 Freeform fields for each install of ExpressionEngine, due to the MySQL column limit, since all fields are stored in a single table. The total limit is also dependent on the type of fields you have, your server setup and encoding type, etc. However, it's very important to note that Freeform fields can be used across all forms, and even be relabelled for each form.
If you plan on having many forms on your site, it may make sense to have some generic naming of fields, and relabel them for each individual form inside Composer. For example, if you need a checkbox for each form that essentially has your site user accept terms and conditions (but the label needs to be a bit different for each form), it'd be better to create a checkbox field once with the name Accept Terms, and then relabel it for each form as necessary, rather than creating 10 different variations of fields.
You can read more about Freeform Fields and Field Types here.
Can I show POST data on the success page?
Answer
Unfortunately you cannot because that data is cleared upon submission, which is done because for security reasons and preventing forms from being submitted more than once, etc.
You can however, consider another approach. Freeform allows you to display submissions on the front end. It also allows you to set the return URL to include the future submission ID. You can set this either in the Return URL field for the form in Composer, or at template level like:
return="{site_url}your-page/success/SUBMISSION_ID"
DANGER
Using this approach can be a security risk as site visitors could try out other ID's in the URL and view submission data for those submissions. It's strongly recommended that you refrain from displaying any sensitive data, but instead use this for anonymous polls or something simple like:
Thanks {submission:first_name:value}, we've received your message and will get back to you shortly!
How do I return form submit to same page with success message?
Answer
Aside from the obvious of using AJAX, you can achieve this by adding a "fake" segment at the end of the URL in your return URL. Then setup a conditional based on that:
{if last_segment == "success"}
<div class="callout success">Your message has been sent.</div>
{if:else}
{exp:freeform_next:render
form="contact_form"
return="{current_url}/success"
}
{/if}
2
3
4
5
6
7
8