Troubleshooting Guide

Common Errors

Error: "Security check failed"

What it means: WordPress nonce verification failed

Common causes:

• Page cached for too long
• Session expired (24+ hours)
• Browser cookies disabled
• Plugin conflict

Solutions:

1. Clear cache: Clear WordPress cache and browser cache
2. Refresh page: Hard refresh (Ctrl+F5 or Cmd+Shift+R)
3. Check cookies: Ensure browser accepts cookies
4. Logout/Login: Fresh login generates new nonce
5. Disable cache: Temporarily disable caching plugins for testing

Error: "Webhook error 500"

What it means: Your webhook endpoint returned an error

Common causes:

• Syntax error in n8n workflow
• Missing required data
• Malformed JSON response
• API key invalid
• Timeout in workflow

Solutions:

1. Check n8n execution: Look at failed workflow execution
2. View error details: Check "Execution" tab in n8n
3. Test workflow: Use n8n test button with sample data
4. Verify JSON: Ensure response is valid JSON
5. Check API keys: Verify all API credentials are correct

Error: "Webhook error 410: Scenario inactive"

What it means: Make.com or Zapier scenario is turned off

Solutions:

1. Go to Make.com or Zapier dashboard
2. Find your scenario/zap
3. Turn it ON
4. Test again

Error: "Form submission failed"

What it means: AJAX request failed before reaching webhook

Common causes:

• JavaScript error on page
• Network connection issue
• WordPress admin-ajax.php blocked
• Plugin conflict

Solutions:

1. Check console: Open DevTools (F12) → Console tab
2. Look for errors: Red error messages indicate issues
3. Test connection: Try on different network/device
4. Disable plugins: Test with other plugins disabled
5. Check server: Verify server is responding

Error: "File too large"

What it means: Uploaded file exceeds size limit

Current limits:

• Per file: 25MB
• Total upload: 100MB

Solutions:

1. Compress images: Use TinyPNG.com or similar
2. Reduce dimensions: Resize images before upload
3. Split files: Upload in multiple submissions
4. Increase PHP limit: Edit php.ini (requires server access)

; In php.ini
upload_max_filesize = 50M
post_max_size = 100M

Form Issues

Form Not Displaying

Symptoms:

• Blank space where form should be
• Only shortcode text shows
• Page loads but no form

Solutions:

1. Check shortcode syntax:

✅ Correct: [ai_agent_form id="123"]
❌ Wrong: [ai_agent_form id=123]
❌ Wrong: [ai-agent-form id="123"]

2. Verify agent exists:

• Go to AI Agents in WordPress admin
• Confirm agent ID matches shortcode
• Ensure agent is published (not draft)

3. Check JavaScript errors:

1. Open DevTools (F12)
2. Go to Console tab
3. Look for JavaScript errors
4. Fix or report errors

4. Test with default theme:

• Switch to Twenty Twenty-Four theme
• If form shows, theme conflict exists
• Contact theme developer

Submit Button Not Working

Symptoms:

• Click submit, nothing happens
• Button disabled/grayed out
• Loading forever

Solutions:

1. Check required fields:

• All required fields must be filled
• Red asterisk (*) indicates required
• Browser validation may block submission

2. Verify webhook URL:

• Go to agent edit page
• Check webhook URL is set
• URL should start with https://
• No typos in URL

3. Test webhook separately:

curl -X POST https://your-webhook-url.com \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

4. Check browser console:

• F12 → Console
• Click submit and watch for errors
• Look for CORS or network errors

Validation Not Working

Symptoms:

• Can submit empty required fields
• Invalid email accepted
• Number fields accept text

Solutions:

1. Check field configuration:

• Required checkbox is checked
• Field type is correct (email, number, etc.)
• Pattern/validation rules are set

2. Browser compatibility:

• HTML5 validation requires modern browser
• Update browser to latest version
• Test in Chrome/Firefox for best support

3. JavaScript conflicts:

• Another plugin may override validation
• Test with plugins disabled
• Check console for errors

Results Not Showing

Symptoms:

• Form submits but no response displays
• Loading spinner forever
• Blank result area

Solutions:

1. Check webhook response:

1. Open DevTools (F12) → Network tab
2. Submit form
3. Find admin-ajax.php request
4. Click request → Response tab
5. Verify response contains output_html

2. Verify response format:

✅ Correct:
{
  "success": true,
  "output_html": "<div>Result here</div>"
}

❌ Wrong:
{
  "result": "text only"
}

3. Check webhook timeout:

• If webhook takes > 60 seconds, may timeout
• Optimize workflow to be faster
• Or use async processing + email results

Webhook Issues

Webhook Not Receiving Data

Symptoms:

• n8n execution not triggered
• No data in webhook logs
• Form submits but webhook doesn't run

Solutions:

1. Verify webhook URL:

• Copy URL from n8n/Make/Zapier
• Paste exactly in WordPress agent settings
• Must start with https://
• No extra spaces or characters

2. Check workflow is active:

• n8n: Toggle "Active" in top-right
• Make: Scheduling set to "Immediately"
• Zapier: Zap is "On"

3. Test webhook directly:

curl -X POST https://your-n8n.app/webhook/test \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 123,
    "form_data": {
      "test": "hello"
    }
  }'

4. Check firewall/security:

• Webhook endpoint accessible publicly
• No IP restrictions blocking WordPress
• HTTPS certificate valid

Webhook Timeout Errors

Symptoms:

• "Request timeout" error
• Loading forever then fails
• Partial response received

Common causes:

• AI processing takes too long
• External API slow to respond
• Large file processing
• Complex workflow with many steps

Solutions:

1. Optimize workflow:

• Remove unnecessary nodes
• Reduce wait times
• Cache common responses
• Use faster AI models

2. Implement async processing:

// Return immediate response
return {
  output_html: "<p>⏳ Processing... Results will be emailed to you!</p>",
  success: true
};

// Continue processing in background
// Send email when complete

3. Increase timeout:

• Contact hosting provider to increase PHP timeout
• Default is 60 seconds
• Can increase to 120-300 seconds if needed

CORS Errors

Error message:

Access to XMLHttpRequest blocked by CORS policy

What it means: Webhook on different domain without CORS headers

Solutions:

1. Add CORS headers to webhook response:

// In webhook response
headers: {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'POST',
  'Access-Control-Allow-Headers': 'Content-Type'
}

2. Use same-origin webhook:

• Host webhook on same domain as WordPress
• Or use n8n cloud (handles CORS automatically)

Invalid JSON Response

Error message:

Unexpected token < in JSON at position 0

What it means: Webhook returned HTML instead of JSON

Solutions:

1. Check response format:

• Response must be valid JSON
• Set Content-Type: application/json
• No HTML tags in response

2. Test response in JSON validator:

• Use JSONLint.com
• Paste response to check validity
• Fix any syntax errors

3. Check for error pages:

• 500 error may return HTML error page
• 404 error returns "not found" HTML
• Fix underlying error first

File Upload Issues

Upload Button Not Working

Symptoms:

• Click upload, nothing happens
• Drag & drop doesn't work
• No file selection dialog

Solutions:

1. Check browser compatibility:

• Chrome: ✅ Full support
• Firefox: ✅ Full support
• Safari: ✅ iOS 11+ required
• IE11: ❌ Not supported

2. Check JavaScript errors:

• F12 → Console
• Look for errors when clicking upload
• May indicate plugin conflict

3. Disable browser extensions:

• Ad blockers may interfere
• Privacy extensions may block
• Test in incognito mode

File Preview Not Showing

Symptoms:

• File selected but no thumbnail
• Blank preview area
• Generic icon instead of image

Solutions:

1. Check file format:

• Image must be valid JPG/PNG/GIF
• Corrupted files won't preview
• Try different file

2. Check file size:

• Very large images may not preview
• Reduce image dimensions
• Compress before upload

3. Browser FileReader API:

• Ensure browser supports FileReader
• Update browser to latest version

File Not Sent to Webhook

Symptoms:

• Form submits but webhook doesn't receive file
• File data fields empty
• Only other form fields received

Solutions:

1. Check n8n payload:

// Should contain:
{
  "field_name_file_data": "base64string...",
  "field_name_file_name": "photo.jpg",
  "field_name_file_type": "image/jpeg",
  "field_name_file_size": 245678
}

2. Check file size limits:

• File must be < 25MB
• Total < 100MB
• Reduce file size if exceeds

3. Check PHP settings:

; Required in php.ini
upload_max_filesize = 25M
post_max_size = 100M
memory_limit = 256M

4. Test with small file first:

• Upload 1KB text file
• If works, issue is file size
• If doesn't work, issue is configuration

Debug Mode

Enabling WordPress Debug Mode

Debug mode helps identify PHP errors and warnings.

Edit wp-config.php:

// Enable debug mode
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);

What each does:

• WP_DEBUG - Enables debug mode
• WP_DEBUG_LOG - Logs errors to file
• WP_DEBUG_DISPLAY - Don't show errors on page
• SCRIPT_DEBUG - Use unminified JS/CSS

Enabling Plugin Debug Logs

Coming in v1.1: Plugin-specific debug logging

// In wp-config.php
define('WP_AI_CONNECTOR_DEBUG', true);

Will log:

• Form submissions
• Webhook requests/responses
• File upload details
• Validation errors

Reading Logs

WordPress Debug Log

Location: /wp-content/debug.log

Access via:

• FTP/SFTP client
• File Manager in cPanel
• SSH: tail -f /path/to/wp-content/debug.log

Reading the log:

[09-Jan-2025 10:30:45 UTC] PHP Warning: ...
[09-Jan-2025 10:30:46 UTC] PHP Fatal error: ...

What to look for:

• PHP Fatal error - Breaks execution
• PHP Warning - Issue but continues
• PHP Notice - Minor issue
• Stack traces - Show where error occurred

n8n Execution Logs

Viewing executions:

1. Go to n8n dashboard
2. Click "Executions" in left sidebar
3. Find your failed execution
4. Click to view details

Understanding execution view:

• Green checkmark = Success
• Red X = Failed
• Click node to see its input/output
• Error message shows cause

Browser DevTools

Opening DevTools:

• Chrome/Edge: F12 or Ctrl+Shift+I
• Firefox: F12 or Ctrl+Shift+K
• Safari: Cmd+Option+I (enable first in prefs)

Console Tab:

• Shows JavaScript errors
• Red text = Error
• Yellow = Warning
• Click to expand for details

Network Tab:

• Shows all HTTP requests
• Find admin-ajax.php for form submissions
• Click request → Response to see webhook response
• Red status = Failed (4xx, 5xx)

Get Support

Before Contacting Support

Please gather this information first:

1. WordPress version: Dashboard → Updates
2. Plugin version: Plugins page
3. PHP version: Tools → Site Health
4. Theme name and version
5. Error message: Exact text or screenshot
6. Steps to reproduce: How to trigger the error
7. Browser and version
8. Debug log: Last 20 lines of debug.log

Support Channels

1. Documentation

• Search this documentation first
• Check Getting Started
• Review Form Builder guide
• Read Webhook Integration

2. WordPress.org Support Forum

• Free community support
• Other users may have same issue
• Searchable archive
• Response within 24-48 hours

3. GitHub Issues

• Report bugs
• Request features
• View known issues
• Track development

4. Email Support

• support@wpaiconnector.com
• Include version info
• Attach screenshots
• Response within 1-2 business days

Creating Good Bug Reports

Good bug report template:

**Environment:**
- WordPress: 6.4.2
- Plugin: WP AI Connector 1.0.0
- Theme: GeneratePress 3.4.0
- PHP: 8.1
- Browser: Chrome 120

**Issue:**
Form submit button doesn't work on mobile devices.

**Steps to reproduce:**
1. Visit agent page on iPhone
2. Fill out all required fields
3. Tap "Submit" button
4. Nothing happens

**Expected behavior:**
Form should submit and show loading state.

**Actual behavior:**
Button tap has no effect. No errors in console.

**Screenshots:**
[Attach screenshot]

**Additional info:**
Works fine on desktop Chrome and Firefox.
Only happens on mobile (tested iOS Safari and Chrome).

Common Support Questions

Q: How do I update the plugin safely?
A: Backup your site first, then update via WordPress dashboard. Test on staging site if possible.

Q: Can I migrate agents to another site?
A: Yes, use WordPress export/import or a migration plugin. Agents are custom post types.

Q: Does it work with Elementor/Divi/Beaver?
A: Yes! Use the shortcode widget to embed forms in page builders.

Q: Can I use multiple agents on one page?
A: Yes, each agent has unique ID. Add multiple shortcodes: [ai_agent_form id="1"] [ai_agent_form id="2"]

Q: How do I translate the plugin?
A: Plugin is translation-ready. Use Loco Translate plugin or .po file editor.

Feature Requests

Have an idea for improvement?

• Check if already requested on GitHub
• Describe the use case clearly
• Explain the benefit
• Include mockups if applicable

We review all requests and prioritize based on:

• Number of requests
• Use case value
• Technical feasibility
• Alignment with roadmap