Troubleshooting

This section covers the most common issues encountered when running LicenceForge, along with diagnostic steps and solutions. Start with the topic that matches your problem, or enable debug mode to gather detailed logs before investigating.

Before you begin

Many issues can be resolved by ensuring you are running the latest version of LicenceForge and that your server meets the system requirements. Check for plugin updates before diving into specific troubleshooting steps.

Troubleshooting Topics

License Issues
Licenses not activating, showing as invalid, incorrect activation counts, and grace period problems.
Update Issues
Updates not appearing, hash mismatches on downloads, expired download tokens, and transient caching.
Payment Issues
WooCommerce not creating licenses, Stripe webhook failures, duplicate licenses, and subscription renewals.
API Issues
Rate limiting (429), authentication errors (401), permission denied (403), and CORS configuration.
Debug Mode & Diagnostics
Enabling WordPress debug logging, reading audit logs, inspecting webhook events, health checks, and WP-CLI commands.

Quick Reference

The table below maps common error messages and symptoms to the relevant troubleshooting page.

Symptom or Error Likely Category Page
License key is invalid License validation failure License Issues
Activation limit reached Too many active sites License Issues
No update available in WordPress Transient cache or rollout exclusion Update Issues
Hash mismatch during download ZIP file changed after hash calculation Update Issues
Download token expired Server time out of sync Update Issues
WooCommerce order completed but no license Product tier not linked Payment Issues
Stripe webhook returns 400 or 500 Webhook secret mismatch Payment Issues
429 Too Many Requests Rate limit exceeded API Issues
401 Unauthorized Missing or invalid API key API Issues
CORS errors in browser console REST API header misconfiguration API Issues

Still Need Help?

If the troubleshooting guides in this section do not resolve your issue:

  1. Enable debug mode and reproduce the problem to capture detailed log output.
  2. Check the wplf_audit_log and wplf_webhook_events tables for error details.
  3. Run the built-in health check from LicenceForge > Settings > Health or via the /wplf/v1/health REST endpoint.
  4. Contact support at licenceforge.com with your debug log and health check results attached.