> ## Documentation Index
> Fetch the complete documentation index at: https://help.topformbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Common issues and solutions to help you resolve problems quickly.

## Table of Contents

* [Form Building Issues](#form-building-issues)
* [Form Submission Issues](#form-submission-issues)
* [Email Notification Issues](#email-notification-issues)
* [Integration Issues](#integration-issues)
* [Analytics Issues](#analytics-issues)
* [Custom Domain Issues](#custom-domain-issues)
* [Account & Authentication Issues](#account--authentication-issues)
* [Performance Issues](#performance-issues)
* [Payment Issues](#payment-issues)
* [General Issues](#general-issues)

***

## Form Building Issues

### Cannot Add Questions

**Problem:** "Add Question" button not working

**Solutions:**

1. **Check Plan Limits** - Free plan limited to 10 questions per form
2. **Reload Page** - Browser cache issue
3. **Check Permissions** - Need edit access to form
4. **Browser Compatibility** - Try Chrome/Firefox/Safari latest version
5. **Disable Browser Extensions** - Ad blockers may interfere

### Form Not Saving

**Problem:** Changes not saved when clicking "Save"

**Solutions:**

1. **Check Internet Connection** - Must be online to save
2. **Look for Error Message** - Red notification with details
3. **Check Required Fields** - Some settings must be filled
4. **Browser Console** - Press F12, check for errors
5. **Try Again** - Temporary server issue
6. **Clear Cache** - Hard refresh (Ctrl+Shift+R)

### Questions Disappeared

**Problem:** Questions deleted or missing

**Solutions:**

1. **Check Version History** - Form Builder → History
2. **Restore Previous Version** - Find version before deletion
3. **Check If Different Form** - Verify form name
4. **Team Member Changes** - Check activity log
5. **Contact Support** - We may have backups

### Conditional Logic Not Working

**Problem:** Logic rules not triggering correctly

**Check:**

1. **Rule Priority** - Rules with higher priority run first
2. **Condition Values** - Exact match required (case-sensitive)
3. **Question Order** - Logic question must come before target
4. **Multiple Rules** - May be conflicting
5. **Test with Preview** - Fill form to test logic

**Debug:**

* Form Builder → Logic tab → Review all rules
* Test each rule individually
* Check condition operators (equals, contains, etc.)
* Verify target blocks exist

### Form Builder Loading Slowly

**Problem:** Form builder takes long time to load

**Solutions:**

1. **Large Form** - 50+ questions may be slow
2. **Clear Browser Cache** - Ctrl+Shift+Delete
3. **Disable Extensions** - Temporarily disable ad blockers
4. **Check Internet Speed** - Run speed test
5. **Try Different Browser** - Chrome recommended
6. **Close Other Tabs** - Free up browser memory

***

## Form Submission Issues

### "Form Not Found" Error

**Problem:** Users see 404 or "Form not found" when opening form

**Solutions:**

1. **Check Form Status** - Must be "Published" not "Draft"
2. **Verify URL** - Check slug is correct
3. **Custom Domain** - Ensure SSL is active
4. **Form Not Deleted** - Verify in dashboard
5. **Workspace Access** - Check form still in workspace

### Form Closed Message

**Problem:** "This form is closed" message appearing

**Solutions:**

1. **Check Closing Date** - Form Settings → Closing
2. **Extend Deadline** - Update closing date
3. **Remove Closing** - Toggle off closing date
4. **Timezone** - Check if timezone correct
5. **Reopen Form** - Save updated settings

### Password Protection Not Working

**Problem:** Correct password not accepted

**Solutions:**

1. **Case Sensitive** - Check uppercase/lowercase
2. **Extra Spaces** - Remove spaces before/after
3. **Wrong Password** - Verify in Form Settings
4. **Reset Password** - Set new password in settings
5. **Clear Browser Cookies** - Old session may interfere

### Submissions Not Being Recorded

**Problem:** Users submit but submission not in dashboard

**Check:**

1. **Form Status** - Must be published
2. **Submission Count** - Verify submissions tab
3. **Filters Applied** - Remove any active filters
4. **Date Range** - Check viewing all dates
5. **Test Submission** - Submit test to verify
6. **Database Issue** - Contact support if persists

**Verify:**

* Check total submission count on form card
* Look in "All Submissions" (not just completed)
* Check abandoned submissions
* Verify user completed (not abandoned mid-form)

### reCAPTCHA Not Showing

**Problem:** reCAPTCHA checkbox missing from form

**Solutions:**

1. **Check Settings** - Form Settings → reCAPTCHA enabled?
2. **API Keys** - Admin must configure reCAPTCHA keys
3. **Browser Compatibility** - Update browser
4. **JavaScript Disabled** - Enable JavaScript
5. **Ad Blocker** - May block reCAPTCHA
6. **VPN/Proxy** - May interfere with reCAPTCHA

### File Upload Failing

**Problem:** Cannot upload files to form

**Check:**

1. **File Size** - Max 10MB per file (default)
2. **File Type** - Check allowed file types in settings
3. **Browser** - Some browsers have issues with large files
4. **Internet Speed** - Slow connection may timeout
5. **Storage Quota** - Plan may have storage limit
6. **File Name** - Remove special characters

**Tips:**

* Compress large files before uploading
* Use supported formats (PDF, images, docs)
* Check file isn't corrupted
* Try different browser

***

## Email Notification Issues

### Not Receiving Emails

**Problem:** No email received after form submission

**Check:**

1. **Spam Folder** - Check junk/spam folder
2. **Email Address** - Verify correct in Form Settings
3. **Notifications Enabled** - Form Settings → Notifications ON
4. **SMTP Configured** - Workspace email settings
5. **Email Template** - Template assigned to form
6. **Test Email** - Send test from settings

**Verify:**

* Form Settings → Notifications → Admin Email → Correct address
* Check workspace SMTP settings
* Look in all email folders (spam, promotions, updates)
* Add [noreply@topformbuilder.com](mailto:noreply@topformbuilder.com) to contacts
* Check email quota not full

### Emails Going to Spam

**Problem:** Emails landing in spam folder

**Solutions:**

1. **Add to Contacts** - Add sender to address book
2. **Mark as Not Spam** - In email client
3. **Custom SMTP** - Use your own email server
4. **SPF Records** - Configure for custom domain
5. **Email Content** - Avoid spam trigger words

**Long-term Fix:**

* Workspace Settings → Email Settings → Configure SMTP
* Use custom domain email (not Gmail/Yahoo)
* Add SPF and DKIM records
* Build sender reputation

### Email Template Variables Not Working

**Problem:** Variables show as `{{variable_name}}` in emails

**Solutions:**

1. **Check Variable Name** - Must match exactly
2. **Question Title** - Variable based on question title
3. **Spaces in Variables** - Use `{{variable}}` not `{{ variable }}`
4. **Question Answered** - Variable empty if not answered
5. **Test Template** - Send test email to verify

**Debug:**

* Form Settings → Notifications → View Variables
* Copy exact variable name
* Paste into template
* Send test email

### Wrong Email Template Used

**Problem:** Different template sent than configured

**Solutions:**

1. **Check Form Settings** - Verify selected template
2. **Resave Settings** - Re-select template and save
3. **Cache Issue** - Wait 5 minutes for cache clear
4. **Test Again** - Submit new test
5. **Verify Workspace** - Using correct workspace

***

## Integration Issues

### Integration Not Sending Data

**Problem:** Integration configured but data not reaching service

**Check:**

1. **Integration Status** - Toggle is ON?
2. **Authentication** - Reconnect OAuth/API key
3. **Destination** - Correct channel/sheet/board selected?
4. **Conditional Logic** - Conditions met?
5. **Integration Logs** - View error messages
6. **Service Status** - External service operational?

**Debug Steps:**

1. Go to Integrations tab
2. Click integration
3. View Logs
4. Check for error messages
5. Re-authenticate if needed

### Slack Messages Not Appearing

**Problem:** Slack integration active but no messages

**Solutions:**

1. **Channel Access** - Bot invited to channel?
2. **OAuth Expired** - Reconnect Slack
3. **Channel Changed** - Verify channel still exists
4. **Test Integration** - Send test message
5. **Slack Workspace** - Correct workspace connected?

**Verify:**

* `/invite @TopFormBuilder` in Slack channel
* Integration logs show success
* Slack app not suspended
* Correct workspace and channel

### Webhook Timing Out

**Problem:** Webhook integration shows timeout errors

**Solutions:**

1. **Endpoint Speed** - Must respond within 30 seconds
2. **Verify URL** - Check webhook URL is correct
3. **HTTPS Required** - HTTP URLs not supported
4. **Firewall** - Whitelist TopFormBuilder IPs
5. **Server Load** - Check server capacity

**Test:**

* Use webhook testing service
* Check endpoint logs
* Verify signature validation not slowing response
* Use async processing on receiving end

### Google Sheets Not Updating

**Problem:** Submissions not adding rows to Google Sheets

**Check:**

1. **OAuth Valid** - Reconnect Google account
2. **Sheet Access** - Account has edit permission?
3. **Sheet Deleted** - Verify sheet still exists
4. **Column Mapping** - Verify field mapping
5. **Rate Limit** - Google Sheets API limits

**Fix:**

* Integration Settings → Reconnect Google
* Verify spreadsheet URL still valid
* Check integration logs for errors
* Test with new submission

***

## Analytics Issues

### No Analytics Data

**Problem:** Analytics dashboard empty or not loading

**Solutions:**

1. **Pro Plan Required** - Analytics is Pro feature
2. **No Submissions Yet** - Need at least 1 view
3. **Date Range** - Check selected date range
4. **Form Published** - Draft forms don't track analytics
5. **Refresh Page** - Browser cache issue

### Wrong Completion Rate

**Problem:** Completion rate doesn't seem accurate

**Explanation:**

* Completion rate = Completed Submissions ÷ Total Views
* Views include ALL page loads (even refreshes)
* Abandoned submissions NOT counted
* In-progress NOT counted

**Example:**

```
500 views
100 completed
50 abandoned
25 in-progress

Rate = 100/500 = 20%
```

**Normal Rates:**

* Simple forms: 60-80%
* Medium forms: 40-60%
* Long forms: 20-40%

### Charts Not Loading

**Problem:** Charts show loading spinner indefinitely

**Solutions:**

1. **Refresh Page** - Ctrl+R or Cmd+R
2. **Browser Compatibility** - Use modern browser
3. **JavaScript Enabled** - Check browser settings
4. **Ad Blocker** - May block chart library
5. **Internet Connection** - Check connection
6. **Try Different Browser** - Browser-specific issue

***

## Custom Domain Issues

### Domain Verification Failing

**Problem:** "Verification failed" error when adding domain

**Solutions:**

1. **Wait Longer** - DNS can take 24-48 hours
2. **Check DNS Records** - Verify A/CNAME record correct
3. **Remove Extra Spaces** - In DNS value
4. **Cloudflare Users** - Set proxy to "DNS only" (gray cloud)
5. **Use DNS Checker** - dnschecker.org to verify propagation

**Verify:**

* DNS Type: A or CNAME
* Name: subdomain (e.g., "forms")
* Value: Exact match (case-sensitive)
* TTL: Any value (3600 recommended)

### SSL Certificate Not Generating

**Problem:** SSL status shows "Failed"

**Solutions:**

1. **Domain Verified First** - SSL only after verification
2. **HTTP Accessible** - Port 80 must be open
3. **Wait 10 Minutes** - SSL takes 1-10 minutes
4. **Firewall** - Allow Let's Encrypt validation
5. **Contact Support** - Provide domain name

**Check:**

* Visit [http://your-domain](http://your-domain) (not https)
* Should show TopFormBuilder page
* If not, DNS issue

### Form 404 on Custom Domain

**Problem:** Form shows 404 error on custom domain

**Solutions:**

1. **Domain Assigned** - Form Settings → Custom Domain selected?
2. **SSL Active** - Check SSL status is "Active"
3. **Save Form** - Resave form settings
4. **DNS Propagation** - Wait for DNS to update
5. **Clear Cache** - Browser and DNS cache

**Verify:**

* Custom domain SSL status = Active
* Form has custom domain selected in settings
* Try http\:// if https\:// doesn't work (temporarily)

***

## Account & Authentication Issues

### Cannot Login

**Problem:** Password not working or login failing

**Solutions:**

1. **Reset Password** - Use "Forgot Password" link
2. **Check Email** - Verify using correct email
3. **Caps Lock** - Check keyboard
4. **Clear Cookies** - Browser cookies may be corrupted
5. **Try Different Browser** - Browser-specific issue
6. **Account Suspended** - Contact support

### Google OAuth Not Working

**Problem:** "Sign in with Google" button not working

**Solutions:**

1. **Pop-up Blocked** - Allow pop-ups for site
2. **Third-party Cookies** - Enable in browser
3. **Google Account** - Try different Google account
4. **Browser** - Use Chrome/Firefox/Safari
5. **Incognito Mode** - Test in private window

### Session Expired

**Problem:** Keep getting logged out

**Solutions:**

1. **Browser Cookies** - Enable cookies
2. **Incognito Mode** - Don't use for regular work
3. **VPN/Proxy** - May cause issues
4. **Multiple Tabs** - Logout from one affects all
5. **Remember Me** - Check "Keep me logged in"

### Cannot Access Workspace

**Problem:** Workspace not visible or accessible

**Solutions:**

1. **Check Access** - Verify you're a member
2. **Owner Removed You** - Contact workspace owner
3. **Wrong Account** - Logged in with different email?
4. **Workspace Deleted** - Contact owner
5. **Refresh List** - Reload workspaces page

***

## Performance Issues

### Slow Page Loading

**Problem:** Pages take long time to load

**Solutions:**

1. **Internet Speed** - Run speed test
2. **Clear Cache** - Browser cache full
3. **Too Many Tabs** - Close unused tabs
4. **Browser Extensions** - Disable temporarily
5. **Old Browser** - Update to latest version
6. **Large Forms** - 100+ questions load slowly
7. **Check Status Page** - System status

**Optimize:**

* Use Chrome or Firefox
* Clear cache weekly
* Close unused tabs
* Disable unused extensions
* Upgrade internet if slow

### Form Builder Lagging

**Problem:** Drag-and-drop and edits are slow

**Solutions:**

1. **Large Form** - Break into multiple pages
2. **Browser Memory** - Restart browser
3. **Computer Performance** - Close other programs
4. **Simplify Form** - Remove unused questions
5. **Disable Animations** - Browser settings

### Submission Export Timeout

**Problem:** Cannot export submissions (timeout error)

**Solutions:**

1. **Too Many Submissions** - Export in smaller date ranges
2. **Large Files** - File uploads slow export
3. **Try Different Format** - CSV faster than Excel
4. **Filter Data** - Export specific fields only
5. **Contact Support** - For very large exports (10,000+)

***

## Payment Issues

### Stripe Payment Failing

**Problem:** Payment field shows error

**Solutions:**

1. **Stripe Connected** - Workspace Settings → Payments
2. **Test Mode** - Using test card in test mode?
3. **Card Details** - Verify card info correct
4. **Card Declined** - Contact bank
5. **Currency Supported** - Check currency available
6. **Amount Valid** - Check minimum amount

**Test Cards:**

```
Success: 4242 4242 4242 4242
Decline: 4000 0000 0000 0002
```

### Stripe Not Connecting

**Problem:** Cannot connect Stripe account

**Solutions:**

1. **Stripe Account** - Create Stripe account first
2. **Business Type** - Complete Stripe onboarding
3. **Pop-up Blocked** - Allow pop-ups
4. **Try Different Browser** - Browser compatibility
5. **Stripe Status** - Check Stripe status page

***

## General Issues

### Browser Compatibility

**Recommended Browsers:**

* ✅ Chrome 90+ (Recommended)
* ✅ Firefox 88+
* ✅ Safari 14+
* ✅ Edge 90+
* ❌ Internet Explorer (Not supported)

**Issues:**

* Old browsers may have display issues
* Some features require modern JavaScript
* Mobile browsers generally supported

### Mobile Issues

**Problem:** Site not working properly on mobile

**Solutions:**

1. **Update Browser** - Mobile browser outdated
2. **Clear Cache** - Mobile browser cache
3. **Rotate Device** - Some features need landscape
4. **Use Desktop** - For complex form building
5. **Mobile App** - Coming soon

### Data Not Syncing

**Problem:** Changes on one device not appearing on another

**Solutions:**

1. **Refresh Page** - Reload to get latest data
2. **Check Internet** - Must be online
3. **Different Workspaces** - Verify same workspace
4. **Save Changes** - Ensure changes saved first
5. **Clear Cache** - Both devices

### Error Messages

**"Something went wrong"**

* Generic error - Check browser console (F12)
* Refresh page
* Try again in a few minutes
* Contact support if persists

**"Unauthorized"**

* Not logged in - Login again
* Session expired - Re-authenticate
* No permission - Contact workspace owner

**"Rate limit exceeded"**

* Too many requests - Wait 1 minute
* Try again slower
* Contact support if blocking work

**"Service unavailable"**

* Server maintenance - Check status page
* Temporary issue - Wait 5-10 minutes
* Try different region if Enterprise

***

## Getting Help

### Before Contacting Support

1. **Check This Guide** - Solution may be here
2. **Search Documentation** - Full docs at docs.topformbuilder.com
3. **Check Status Page** - System-wide issues posted
4. **Try Basic Fixes** - Refresh, clear cache, different browser
5. **Gather Information** - Error messages, screenshots, steps to reproduce

### How to Contact Support

**Email:** [contact@topformbuilder.com](mailto:contact@topformbuilder.com)

**Include in Your Message:**

* Clear description of issue
* Steps to reproduce
* Expected vs actual behavior
* Error messages (full text)
* Screenshots (if applicable)
* Browser and OS
* Account email
* Form/workspace URL (if relevant)

**Response Time:**

* Pro: Within 24 hours
* Enterprise: Within 4 hours
* Critical issues: Priority response

### Useful Information to Provide

**For Form Issues:**

* Form URL or slug
* Workspace name
* When issue started
* If affects all users or just you
* Screenshots of error

**For Integration Issues:**

* Integration type (Slack, Sheets, etc.)
* Error message from logs
* Last successful integration
* Changes made recently
* Screenshot of integration settings

**For Account Issues:**

* Account email
* When issue started
* Error message
* Login method (email, Google)
* Browser and device

### Community Resources

**Knowledge Base:**

* docs.topformbuilder.com

**Video Tutorials:**

* Coming soon

**System Status:**

* status.topformbuilder.com

**Feature Requests:**

* Contact support or use in-app feedback

***

## Preventive Measures

### Regular Maintenance

**Weekly:**

* Review form submissions
* Check integration logs
* Test critical forms
* Review error notifications

**Monthly:**

* Update team access
* Clean up old test forms
* Export important data
* Review analytics
* Check custom domain SSL

**Quarterly:**

* Change workspace passwords
* Rotate API keys
* Audit user permissions
* Review security settings
* Update email templates

### Best Practices

**To Avoid Issues:**

* Test forms before sharing
* Use supported browsers
* Keep software updated
* Save work frequently
* Backup important forms
* Document settings
* Train team properly
* Monitor usage limits

***

[**Still need help? Contact contact@topformbuilder.com**](mailto:contact@topformbuilder.com)