Troubleshooting Guide

This guide provides solutions for common issues you might encounter while building forms in FluidForms. It covers problems with Liquid templating, conditional logic, integrations, and more.

General Debugging Tips

When your form isn't behaving as expected, start with these general debugging techniques.

1. Use Preview Mode Extensively

Preview mode is your first line of defense. Test your form thoroughly after every significant change. Fill out fields with different values to test all possible paths and edge cases.

2. Use the Browser Developer Tools

Your browser's developer tools (usually opened with F12 or Ctrl+Shift+I) are invaluable. The Console tab will show you any JavaScript errors that might be breaking your form's functionality.

3. Output Values for Debugging

A powerful way to inspect the state of your form is to temporarily output values directly into a paragraph or text field.

DEBUG: {{ email }} - {{ age }}

This will display the current values of specific fields, helping you see exactly what data your logic is working with.

Common Liquid Issues

Syntax Errors

• Problem: Using {{ }} for logic tags instead of {% %}.
• Incorrect: {{ if age >= 18 }}
• Correct: {% if age >= 18 %}

Forgetting to Close Tags

• Problem: An if, for, or other block is not closed, causing rendering to fail.
• Incorrect: {% if condition %} ...
• Correct: {% if condition %} ... {% endif %}

Incorrect Variable Access

• Problem: Trying to access a form field value using the deprecated values object.
• Incorrect: {{ values.email }}
• Correct: {{ email }}

Missing Default Values

• Problem: A calculation fails because a field is empty (nil or null).
• Incorrect: {{ price | times: quantity }}
• Correct: {{ price | default: 0 | times: quantity | default: 1 }}

String vs. Number Issues

• Problem: Trying to perform math on a value that is a string.
• Solution: Liquid automatically handles type conversion for basic math operations. However, if you need to ensure a value is treated as a number (e.g. for strict comparisons), you can add 0.
• Example: {% assign numeric_value = "5" | plus: 0 %}

Conditional Logic & Navigation

Logic Not Triggering or Field Not Hiding

1. Check Field Names: Ensure the field name in your Liquid expression is the static name set in the properties panel, not the label. Field names are case-sensitive.
2. Verify the Logic: Double-check your if condition. Use debug output to see the exact value you are checking against.
3. Boolean Logic: For hidden properties, ensure your expression correctly returns true (to hide) or false (to show).

Navigation Not Working

1. Check Section Names: The name returned by your Liquid expression in the "Go To Section" property must exactly match the target section's name (case-sensitive).
2. Test All Paths: Make sure every possible outcome of your Liquid expression corresponds to a valid section name. An expression that returns an invalid or empty name will break navigation.
3. Ensure a Path to "Thank You": All logical paths must eventually lead to a section with mode: "thankyou".

Integration & Webhook Problems

Webhook Not Firing

1. Check the URL: Verify that the URL is correct and publicly accessible. Use a tool like RequestBin or webhook.site to test if the endpoint is receiving requests at all.
2. Check Server Logs: If you are hosting your own endpoint, check your server logs for incoming requests.

Authentication Errors

• Problem: Your endpoint returns a 401 Unauthorized or 403 Forbidden error.
• Solution: Currently, FluidForms webhooks do not support custom authentication headers. Ensure your endpoint is accessible or uses a secret token in the URL query parameters (e.g., https://api.example.com/webhook?token=SECRET).

Performance Issues

Slow Form Loading or Calculations

• Problem: The form is slow to respond, especially when filling out fields that trigger Liquid calculations.
• Solution: Optimize your Liquid code.
  • Avoid Repeated Calculations: If you use the same complex calculation multiple times, compute it once and store the result in a variable using {% assign %}.
  • Minimize Loops: Nested for loops can be slow. Try to use array filters like map or where to process data more efficiently.

Example: Inefficient vs. Efficient Calculation

Inefficient:

Subtotal: {{ price | times: quantity }}
Tax: {{ price | times: quantity | times: 0.1 }}
Total: {{ price | times: quantity | times: 1.1 }}

Efficient:

{% assign subtotal = price | times: quantity %}
Subtotal: {{ subtotal }}
Tax: {{ subtotal | times: 0.1 }}
Total: {{ subtotal | times: 1.1 }}