# Troubleshooting

> Solutions to common issues with WPsigner installation, configuration, signing, and document processing.

edition: both
Edition: Lite + Pro
AI note: This page applies to Lite and Pro. Call out Lite limits (PDF only, max 2 signers, email OTP, local timestamp) when they apply. Do not invent Pro-only features.
HTML: https://docs.wpsigner.com/support/troubleshooting/
Markdown: https://docs.wpsigner.com/md/support/troubleshooting.md
Source file: support/troubleshooting.md

---

This guide covers the most common issues you might encounter with WPsigner and provides step-by-step solutions.

## Quick Diagnostics

Before troubleshooting specific issues, check the System Status:

1. Go to **WPsigner → More → System Status**
2. Review all health checks
3. Address any items marked with ⚠️ or ❌

---

## Installation Issues

### "Plugin could not be activated"

**Symptoms:**
- Error message on activation
- White screen after activation
- Plugin immediately deactivates

**Causes & Solutions:**

| Cause | Solution |
|-------|----------|
| **PHP version too low** | Upgrade to PHP 7.4 or higher |
| **Missing OpenSSL** | Enable OpenSSL extension |
| **Memory limit** | Increase to 128MB minimum |
| **Plugin conflict** | Deactivate other plugins to identify conflict |

**How to check PHP version:**
```bash
php -v
```

**How to enable debug mode:**
Add to `wp-config.php`:
```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```
Then check `/wp-content/debug.log` for specific errors.

### "Upload failed - file size exceeds limit"

**Symptoms:**
- Cannot upload plugin zip file
- Error during upload process

**Solutions:**

1. **Increase PHP upload limits** in `php.ini`:
```ini
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
```

2. **Or use FTP upload method:**
   - Extract the zip file locally
   - Upload via FTP to `/wp-content/plugins/`
   - Activate in WordPress admin

### Fatal error on activation

**Full error message check:**
1. Enable debug mode (see above)
2. Try activating again
3. Check `/wp-content/debug.log`
4. Search for the specific error

**Common fatal errors:**

| Error | Solution |
|-------|----------|
| `Cannot redeclare function` | Plugin conflict - identify and deactivate |
| `Class not found` | Missing dependency - reinstall plugin |
| `Memory exhausted` | Increase `WP_MEMORY_LIMIT` |

---

## Form integrations (Fluent Forms / WPForms)

### OTP says verified, but submit fails

**Symptoms:**
- OTP modal shows **Identity verified**
- Form then shows “Please verify your identity…” (or similar)
- No signed document is created

**Solution:**
1. Update **WPsigner to 3.1.1+**
2. Hard-refresh the form page (Ctrl+F5 / Cmd+Shift+R)
3. Submit again and complete OTP once

This mainly affects **content signing** forms with many fields + OTP. See [Fluent Forms](/integrations/fluent-forms/), [Formidable Forms](/integrations/formidable-forms/), and [WPForms](/integrations/wpforms/).

### Fluent Forms CC did not receive the signed PDF

1. Update to **WPsigner 3.2.8+**.
2. In the feed, set **CC email field** to the form’s Email/CC field (do not paste `{inputs...}` into **Additional CC emails**).
3. Submit a test and confirm that field contains a real email.

See [Fluent Forms → CC emails](/integrations/fluent-forms/#cc-emails-optional).

### E2Pdf dropdown is missing on the Formidable feed

E2Pdf is a separate plugin. Install and activate it. WPsigner does not bundle it, and there is no E2Pdf card in **Integrations**. Guide: [E2Pdf](/integrations/e2pdf/).

If the dropdown is there but your template is not, the template must use **extension = Formidable**. WPsigner lists created templates even when they are not yet license-activated in E2Pdf (those rows show **not activated in E2Pdf**). Trashed templates stay hidden.

### Formidable + E2Pdf created no document

1. Update to **WPsigner 3.2.12+**.
2. Confirm the E2Pdf template uses **extension = Formidable** and **item = that form**.
3. Map Name + Email on the feed. Do not add the **WPsigner Signing** field on an E2Pdf form.
4. Check `wp-content/debug.log` for `[inSigner FormidableE2Pdf]`.

### Formidable says “Your entry appears to be blocked spam!” {#formidable-blocked-spam}

That text is from **Formidable**, not WPsigner. Formidable was scanning the signature PNG (a large base64 string) against its denylist and WordPress **Disallowed Comment Keys**.

1. Update to **WPsigner 3.2.12+** (the signing field is skipped, like Formidable’s native Signature field).
2. Name, email, and message are still checked.
3. If it continues after the update, check Formidable → Global Settings → Spam, or another anti-spam plugin (CleanTalk, Akismet).

### Formidable WPsigner Signing field looks like a text box

Formidable 6 was converting the custom type to `text`. **3.2.12+** registers a real field type so the pad stays Draw / Type / Upload. Hard-refresh the form after updating.

### No Download Signed PDF after Formidable content signing

The button is added to Formidable’s **Show message** confirmation. If the form redirects to another URL, add `{inSigner:download_button}` there or in the notification email. Guide: [Formidable Forms — Download](/integrations/formidable-forms/#download-the-signed-pdf).

### WooCommerce lists WPsigner as incompatible

WPsigner declares HPOS and Cart/Checkout Blocks. If you just hit a fatal and recovery mode was on, WooCommerce did not see that declaration.

1. Update to **3.2.12+** (declaration runs even in recovery mode).
2. Click **re-enable the plugin** if the recovery notice is still there.
3. On Plugins, switch the filter from *Incompatible with WooCommerce features* to **All**.

---

## Access codes

### The signer cannot request the code

**Request access code** only appears for a **random** code sent after **3.2.8**, and only to the email or phone already on that signer. A code you typed (SSN last-4, date of birth) cannot be resent from the signing page. Share it separately, or the signer enters the secret they already know.

### The access-code page does not mention SSN / date of birth

On Review, choose **I’ll set the access code** and fill **Signer prompt** (or use a preset). The prompt is not shown for a random PIN.

See [Access codes](/core-features/security-compliance/#access-codes).

### Cannot save a content-signing feed

**Symptoms:**
- Feed Name and Form are filled
- Save shows “Please fill in Feed Name and Form”
- You are not using a PDF template (inline Signing field)

**Solution:** Update to **3.1.1+**. Content-signing feeds do not require a template — only Feed Name and Form.

### Wrong signer name on the document

Map a real **Name** / **Names** field. Do not map a field labeled only **Username**.

### Field labels missing in feed mapping

In the PDF editor, **double-click** each field and set a **Field name**. Details: [Form fields](/core-features/form-fields/#field-name-mapping-name-and-placeholder).

---

## Email Issues

### Emails not sending

This is the most common issue. Emails may not send for several reasons.

**Step 1: Verify email configuration**
1. Go to **WPsigner → Settings → Email Settings**
2. Verify "From Name" and "From Email" are set
3. Ensure email address is valid

**Step 2: Send a test email**
1. Go to **WPsigner → More → Email Templates**
2. Click **Send Test**
3. Enter your email address
4. Check if received

**Step 3: Configure SMTP**

WordPress's default `wp_mail()` function often fails. Install an SMTP plugin:

| Plugin | Recommendation |
|--------|----------------|
| **WP Mail SMTP** | Most popular, easy setup |
| **FluentSMTP** | Free, full-featured |
| **Post SMTP** | Good logging |

**Step 4: Check SMTP logs**

Most SMTP plugins have logging. Check for:
- Connection errors
- Authentication failures
- Rejected recipients

### Emails going to spam

**Causes:**
- No SPF/DKIM records
- Using @gmail.com as sender
- Poor sender reputation
- Missing authentication

**Solutions:**

1. **Use your own domain** for "From Email" (not @gmail.com)

2. **Set up email authentication:**
   - Add SPF record to DNS
   - Configure DKIM signing
   - Set up DMARC policy

3. **Check content:**
   - Avoid spam trigger words
   - Don't use all caps
   - Include clear unsubscribe option (if applicable)

### Signer claims they didn't receive email

**Checklist:**
1. ✅ Verify email address is correct (check for typos)
2. ✅ Check spam/junk folder
3. ✅ Check "Promotions" tab (Gmail)
4. ✅ Ask if email was blocked by corporate filter
5. ✅ Use **Resend** option in document actions
6. ✅ Review SMTP logs for delivery status

---

## Document Issues

### Vietnamese or accented characters missing on the signed PDF

**Symptoms:**
- Names look fine on the signing page but the downloaded PDF shows boxes, `?`, or missing marks
- Certificate of Completion drops ă, ơ, ư, đ, or similar

**Solution:**

1. Go to **WPsigner → Languages**
2. Open **Signed PDF fonts**
3. Install **Accented Latin** (Vietnamese and other Latin languages with accents)
4. Click **Use for signed PDFs**
5. Send a **new** test document — already flattened PDFs are not rewritten

For Chinese, Japanese, Korean, Arabic, Hebrew, or Thai, install that pack instead. Guide: [Signed PDF fonts](/customization/languages/#signed-pdf-fonts).

### Require WordPress login will not stay checked

The signer email is not a WordPress user, or the document has an active public campaign. Create the user first, pause the campaign, or leave the option off. Guide: [WordPress login](/core-features/security-compliance/#wordpress-login-per-signer).

### PDF generation failed

**Symptoms:**
- Error when finalizing document
- Certificate of Completion not appending
- Blank or corrupted PDF output

**Required extensions:**

| Extension | Purpose | Check Command |
|-----------|---------|---------------|
| **GD** | Image processing | `php -m | grep gd` |
| **Imagick** | Advanced image/PDF | `php -m | grep imagick` |
| **mbstring** | String handling | `php -m | grep mbstring` |

**Solutions:**

1. **Enable GD extension:**
   ```bash
   # Ubuntu/Debian
   sudo apt-get install php-gd
   sudo service apache2 restart
   ```

2. **Check file permissions:**
   ```bash
   # The uploads directory must be writable
   chmod 755 wp-content/uploads
   chmod 755 wp-content/uploads/wpsigner
   ```

3. **Increase memory limit:**
   Add to `wp-config.php`:
   ```php
   define('WP_MEMORY_LIMIT', '256M');
   ```

### Document upload fails

**Common causes:**

| Issue | Solution |
|-------|----------|
| File too large | Increase `upload_max_filesize` |
| Wrong format | Use PDF, PNG, or JPG only |
| Timeout | Increase `max_execution_time` |
| Permissions | Check `/wp-content/uploads/` is writable |

**Check upload limits:**
1. Go to **WPsigner → More → System Status**
2. Review "Upload Size" value
3. Increase if needed in `php.ini`

### Document appears blank or corrupted

**Possible causes:**
- PDF was created with unsupported features
- PDF is password-protected
- File was corrupted during upload

**Solutions:**
1. Try re-uploading the document
2. Use a simpler PDF (avoid complex layers/fonts)
3. Convert to PDF/A format
4. Remove password protection before uploading

---

## Signing Issues

### Signing page not loading

**Symptoms:**
- White screen when signer clicks link
- 404 error on signing page
- Redirect loop

**Solutions:**

1. **Flush permalinks:**
   - Go to **Settings → Permalinks**
   - Click **Save Changes** (without changing anything)

2. **Check permalink structure:**
   - WPsigner requires "pretty" permalinks
   - Select any option except "Plain"

3. **Check for conflicts:**
   - Disable caching plugins temporarily
   - Try a default theme
   - Deactivate security plugins for testing

### Signature pad not working

**Symptoms:**
- Cannot draw on signature pad
- Signature not appearing
- Pad is unresponsive

**Causes & Solutions:**

| Cause | Solution |
|-------|----------|
| JavaScript error | Check browser console for errors |
| Cache | Clear browser cache, disable caching plugin |
| Plugin conflict | Test in incognito mode |
| Touch issues | Update browser, try different device |

**Browser compatibility:**
- Chrome 80+ ✅
- Firefox 75+ ✅
- Safari 13+ ✅
- Edge 80+ ✅
- Internet Explorer ❌ (not supported)

### "Access denied" or "Invalid link"

**Causes:**
- Link has expired
- Document was voided
- Link was already used (for single-use links)
- Wrong link/typo

**Solutions:**
1. Check document status (expired? voided?)
2. Use **Resend** to generate fresh email
3. Verify the complete URL was clicked

---

## Digital Signature Issues

### "Certificate not found" error

**Symptoms:**
- Error when signing document
- Digital signature not applying
- Adobe shows "Signature is invalid"

**Solutions:**

1. **Configure Digital ID:**
   - Go to **WPsigner → More → Digital ID**
   - Generate or upload a certificate
   - Verify it shows as "Active"

2. **Certificate expired:**
   - Check certificate validity dates
   - Generate new or upload renewed certificate

### Adobe shows "Unknown Signer"

**This is expected for self-signed certificates.**

For self-signed certificates, recipients must manually trust:
1. Click on the signature in Adobe
2. Click "Validate Signature"
3. Choose "Trust this certificate"

**For globally trusted signatures:**
Purchase a certificate from an AATL member (DigiCert, GlobalSign, etc.)

### Timestamp not appearing

**Causes:**
- TSA not enabled
- TSA server unreachable
- Firewall blocking requests

**Solutions:**

1. **Enable TSA:**
   - Go to **WPsigner → Settings → Legal & Privacy**
   - Check "Enable certified timestamp (TSA)"
   - Save settings

2. **Test TSA connection:**
   ```bash
   curl -I https://freetsa.org/tsr
   ```

3. **Try different TSA:**
   - FreeTSA.org
   - DigiCert timestamp server
   - Sectigo timestamp server

---

## Performance Issues

### Plugin is slow

**Optimization steps:**

1. **Enable caching** (but configure WPsigner exclusions)

2. **Optimize database:**
   - Delete old/completed documents you no longer need
   - Use a database optimization plugin

3. **Upgrade hosting:**
   - Move from shared to VPS
   - Ensure adequate PHP memory

4. **CDN for static assets:**
   - Won't help with signing pages
   - Does help general WordPress performance

### Signing page loads slowly

**Causes:**
- Large PDF files
- Slow server
- Multiple large images in document

**Solutions:**
1. Optimize PDF size before uploading
2. Use compression for images
3. Upgrade hosting resources
4. Move to geographically closer hosting for your signers

---

## API Issues

### API returns 401 Unauthorized

**Causes:**
- Invalid API key
- Invalid API secret
- Key revoked
- Missing headers

**Checklist:**
1. Verify API key is active (not revoked)
2. Check both key AND secret are correct
3. Ensure headers are set correctly:
   ```
   X-WPS-API-KEY: your_key_here
   X-WPS-API-SECRET: your_secret_here
   ```

### API returns 403 Forbidden

**Causes:**
- Key has read-only permissions for write endpoint
- User doesn't have required WordPress capabilities

**Solutions:**
1. Check key permissions (read vs read_write)
2. Create new key with appropriate permissions

### Rate limit exceeded

**Default limits:**
- 60 requests per minute per key

**Solutions:**
1. Implement request throttling in your code
2. Use bulk endpoints where available
3. Cache responses to reduce calls

---

## WordPress Conflicts

### Conflict with caching plugins

**Symptoms:**
- Signing page shows cached content
- Changes not appearing
- Session issues

**Solution - Add exclusions:**

| Caching Plugin | Exclusion Pattern |
|----------------|-------------------|
| WP Rocket | Add `/sign/*` to never cache URLs |
| W3 Total Cache | Add to page cache exceptions |
| LiteSpeed | Add to Do Not Cache URIs |
| WP Super Cache | Add to rejected pages |

### Conflict with security plugins

**Common conflicts:**
- Wordfence blocking signing requests
- iThemes Security blocking API
- Sucuri WAF filtering uploads

**Solutions:**
1. Whitelist WPsigner paths (`/sign/*`, `/wp-json/wpsigner/*`)
2. Add WPsigner to trusted plugins
3. Review security logs for blocks

### Theme compatibility issues

**Symptoms:**
- Signing page has theme elements
- Broken layout on signing page
- Missing styles

**Solutions:**
1. WPsigner signing pages should be standalone
2. If theme is interfering, check for forced templates
3. Report to support with theme name

---

## Database Issues

### Missing database tables

**Symptoms:**
- "Table doesn't exist" errors
- Plugin functions not working
- Data not saving

**Solution:**

1. Deactivate and reactivate plugin (triggers table creation)

2. If that fails, manually run table creation:
   - Access your database via phpMyAdmin
   - Check if `wp_wps_*` tables exist
   - If missing, try reinstalling plugin

### Data migration issues

**When upgrading:**
1. Always backup before upgrading
2. Check that database updates run successfully
3. Review changelog for migration notes

---

## Getting More Help

### Information to gather before contacting support

Collect this information for faster resolution:

| Information | How to Get It |
|-------------|---------------|
| WordPress version | Dashboard → At a Glance |
| PHP version | System Status page |
| WPsigner version | Plugins page |
| Error messages | Debug log, browser console |
| Steps to reproduce | Write down exact steps |
| Screenshots | Capture error screens |

### Enable debug mode

For detailed error information:

```php
// Add to wp-config.php (before "That's all, stop editing!")
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

Errors are logged to `/wp-content/debug.log`

### Contact support

If you've tried the troubleshooting steps:

1. Visit [wpsigner.com/contact](https://wpsigner.com/contact/)
2. Include all gathered information
3. Attach debug logs and screenshots
4. Describe expected vs actual behavior

### Mobile app will not pair

The native app needs **Pro 3.2.2+** and **HTTPS**. Full steps: [Connect the mobile app](/mobile-app/connect/).

| Symptom | Fix |
|---------|-----|
| Generate QR is disabled | Serve the site over HTTPS |
| Scan does nothing / code expired | QR lasts 5 minutes — generate a new one |
| Confirmation numbers differ | You scanned a stale QR |
| REST errors or “Could not connect” | Allow `/wp-json/insigner/v1/app*` in the firewall / security plugin |
| Password login fails | Check the WordPress user can use signatures |

Android download: [Google Play](https://play.google.com/store/apps/details?id=com.wpsigner.app). iOS App Store listing is coming soon.

---

## Next Steps

- [System Requirements](/getting-started/requirements/) - Verify compatibility
- [Installation](/getting-started/installation/) - Reinstallation steps
- [FAQ](/support/faq/) - Common questions
- [MainWP Troubleshooting](/addons/mainwp-troubleshooting/) - Dashboard / Clients / Sites contract issues
- [Uncanny Automator Troubleshooting](/addons/uncanny-automator-troubleshooting/) - Recipes, tokens, prefill, and messaging