Debug Mode & Diagnostics

LicenceForge provides several diagnostic tools for investigating issues: WordPress debug logging, the built-in audit log, webhook event inspection, health checks, and WP-CLI commands. This page explains how to use each one effectively.

Enabling WordPress Debug Logging

WordPress debug mode captures PHP errors, warnings, and notices generated by LicenceForge and writes them to a log file instead of displaying them on screen.

Configuration

Add the following constants to your wp-config.php file, before the line that reads /* That's all, stop editing! */:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Log Location

Debug output is written to:

wp-content/debug.log

You can tail this file in real time while reproducing an issue:

tail -f wp-content/debug.log

Disabling Debug Mode

When you have finished investigating, set all three constants back to their production values:

define( 'WP_DEBUG', false );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', false );

Audit Log

The wplf_audit_log table records every significant license operation performed by LicenceForge. It is the primary diagnostic tool for investigating license-related issues without enabling WordPress debug mode.

Table Structure

Querying the Audit Log

View the 20 most recent audit log entries:

wp db query "SELECT id, action, product_slug, outcome, created_at FROM wp_wplf_audit_log ORDER BY id DESC LIMIT 20"

Filter by a specific action (e.g. failed validations):

wp db query "SELECT * FROM wp_wplf_audit_log WHERE action = 'validate' AND outcome = 'failure' ORDER BY id DESC LIMIT 10"

You can also view the audit log through the admin panel at LicenceForge > Audit Log. See Audit Log Panel for details on filtering and exporting.

Webhook Events

The wplf_webhook_events table records all incoming webhook events from Stripe and WooCommerce, including their processing status and any error messages.

Key Column: processing_error

When a webhook event fails to process, the reason is stored in the processing_error column. Common values include:

• Signature verification failed — Webhook secret mismatch
• Product not found for WC product ID — Price tier mapping issue
• License creation failed: duplicate key — Idempotency conflict

Query recent failed webhook events:

wp db query "SELECT event_id, event_type, status, processing_error, created_at FROM wp_wplf_webhook_events WHERE status = 'failed' ORDER BY id DESC LIMIT 10"

Health Checks

LicenceForge includes a built-in health check system that verifies the integrity of your installation. Health checks can be triggered in two ways:

Via the Admin Panel

Navigate to LicenceForge > Settings > Health and click Run Health Check. Results are displayed immediately on the page.

Via the REST API

Send a GET request to the health endpoint:

curl -H "X-LicenceForge-Key: your-api-key" \
  https://your-site.com/wp-json/wplf/v1/health

The response includes the status of each check (database tables, cron jobs, file permissions, encryption, and more). Any check returning warning or error includes a message describing the issue.

WP-CLI Diagnostic Commands

The following WP-CLI commands are useful for diagnosing LicenceForge issues from the command line.

Check Plugin Version

# Installed plugin version
wp option get wplf_version

# Database schema version
wp option get wplf_db_version

List Cron Events

Verify that all LicenceForge cron events are registered and scheduled:

wp cron event list --fields=hook,next_run_relative,recurrence | grep wplf

If any events are missing, deactivate and reactivate the plugin to re-register them.

Check Last Maintenance Run

wp option get wplf_last_maintenance_run

This returns a Unix timestamp. If the value is more than 48 hours old, the daily maintenance cron is not running. See Cron Jobs for troubleshooting steps.

Query Recent Audit Entries

wp db query "SELECT * FROM wp_wplf_audit_log ORDER BY id DESC LIMIT 20"

Inspect LicenceForge Options

wp db query "SELECT option_name, option_value FROM wp_options WHERE option_name LIKE 'wplf_%'"

Common Log Messages

The following messages may appear in debug.log or the audit log. Each entry explains what the message means and whether action is required.

Diagnostic Workflow

When investigating an issue, follow this recommended sequence:

1. Run the health check from LicenceForge > Settings > Health to identify any systemic problems.
2. Check the Audit Log for recent failures related to the affected operation.
3. If the issue involves webhooks, inspect the wplf_webhook_events table for processing errors.
4. If the above steps do not reveal the cause, enable WP_DEBUG temporarily, reproduce the issue, and review debug.log.
5. Disable WP_DEBUG immediately after collecting the relevant log output.

Related Pages

• Health Checks — Full health check reference and alert configuration
• Cron Jobs — Scheduled task configuration and troubleshooting
• Audit Log Panel — Admin panel interface for browsing audit entries
• Security Best Practices — Production hardening recommendations
• License Issues — License validation and activation problems