Update Issues

This page covers problems related to the WordPress plugin update system as it interacts with LicenceForge. Each issue is documented with its symptoms, possible causes, and recommended solutions.

Updates Not Showing in WordPress

Symptom

A new version has been published in LicenceForge, but the customer's WordPress dashboard does not show an available update for the plugin.

Possible Causes

1. License not active. The update check endpoint requires an active license. If the license status is expired, cancelled, or suspended, no update information is returned.
2. Current version is same or newer. WordPress only displays an update when the remote version is strictly greater than the installed version (compared using version_compare()).
3. Rollout percentage excludes this license. If the product uses staged rollouts, the update is only offered to a subset of licenses. LicenceForge uses a deterministic CRC32 hash of the license ID to decide inclusion, so the same license will consistently be included or excluded for a given rollout percentage.
4. WordPress update transient is cached. WordPress caches update check results in the update_plugins site transient. Stale cache data can prevent new updates from appearing.

Solutions

1. Verify the license is active by checking the license status in the LicenceForge admin panel or by calling the validation endpoint.
2. Confirm the published version is greater than the installed version. Check the product's current version in LicenceForge > Products.
3. If using staged rollouts, verify the rollout percentage. Set it to 100% to make the update available to all licenses.
4. Clear the WordPress update transient to force a fresh check:

   wp transient delete update_plugins --network

   Or via PHP:

   delete_site_transient( 'update_plugins' );

Hash Mismatch on Download

Symptom

The update begins downloading but fails with a hash mismatch error. WordPress reports that the downloaded file does not match the expected hash.

Possible Causes

• The product ZIP file was replaced or modified after the hash was calculated by LicenceForge.
• The file was re-uploaded without updating the stored hash.

Solution

In the LicenceForge admin panel, navigate to the product and click the Recalculate Hash button on the product edit page. This re-computes the SHA-256 hash of the current ZIP file and stores the updated value. Customers can then retry the update.

Download Token Expired

Symptom

The update process starts but the download fails with a Download token expired error or an HTTP 403 response.

Possible Causes

• Slow connection. Download tokens are valid for 5 minutes (300 seconds). If the client takes longer than this to initiate the download after receiving the token, the token expires.
• Server time drift. If the server clock is out of sync, token expiry calculations may be incorrect. The token's expiry timestamp is compared against time() on the server.

Solutions

1. Ensure the server clock is synchronised with NTP:

   # Check current time offset
   ntpdate -q pool.ntp.org
   
   # Sync time (requires root)
   sudo ntpdate pool.ntp.org

2. If customers have slow connections, consider increasing the download timeout on the client side. The token validity window is set server-side and is not currently configurable through the admin panel.
3. Retry the update. WordPress will request a fresh token on the next attempt.

Update Shows but Fails to Install

Symptom

WordPress displays the update, and the download succeeds, but the installation fails with a filesystem or memory error.

Possible Causes

• File permissions. The wp-content/plugins/ directory is not writable by the web server process.
• Insufficient disk space. WordPress needs temporary space to extract and replace the plugin files.
• PHP memory limit. Large plugin ZIP files may exceed the available PHP memory during extraction.

Solutions

1. Verify that wp-content/ and wp-content/plugins/ are writable:

   ls -la wp-content/
   ls -la wp-content/plugins/

   Directories should be 755 and owned by the web server user.

2. Check available disk space (aim for at least 100 MB free):

   df -h .

3. Increase the PHP memory limit to at least 256M. Add to wp-config.php:

   define( 'WP_MEMORY_LIMIT', '256M' );

Diagnostic Checklist

Use this checklist to systematically diagnose update problems:

Related Pages

• Version Management — Publishing new versions and managing releases
• Staged Rollouts — Gradual update distribution
• Download Security — Token-based download protection
• Debug Mode — Enabling detailed logging for diagnosis