Troubleshooting

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:

php -v

How to enable debug mode: Add to wp-config.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:

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

---

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

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
Imagick	Advanced image/PDF	`php -m
mbstring	String handling	`php -m

Solutions:

1. Enable GD extension:

   # Ubuntu/Debian
   sudo apt-get install php-gd
   sudo service apache2 restart

2. Check file permissions:

   # 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:

   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:

   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:

// 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
2. Include all gathered information
3. Attach debug logs and screenshots
4. Describe expected vs actual behavior

---

Next Steps

• System Requirements - Verify compatibility
• Installation - Reinstallation steps
• FAQ - Common questions