Troubleshooting Installation

Solutions to common problems encountered when installing and activating DPOKit.

7 min read

Troubleshooting Installation

This page covers the most common issues encountered during installation and initial setup. If your problem is not listed here, open a support ticket from your customer dashboard or post in the community forum.

Fatal errors on activation

"Plugin could not be activated because it triggered a fatal error"

Cause: PHP version below 8.1, or a syntax/compatibility conflict with another plugin.

Fix:

  1. Check your PHP version: go to Tools → Site Health → Info → Server and look for PHP version.
  2. If below 8.1, upgrade PHP through your hosting control panel (cPanel, Kinsta, WP Engine, etc.).
  3. If PHP is already 8.1+, deactivate all other plugins, activate DPOKit, then reactivate other plugins one at a time to identify the conflict. Report conflicts to support.

White screen of death (WSOD) after activation

Cause: PHP memory exhaustion or a fatal class conflict.

Fix:

  1. Add the following to wp-config.php above the /* That's all, stop editing! */ line: 
    define( 'WP_MEMORY_LIMIT', '256M' );
  2. If the WSOD persists, enable WordPress debug mode to surface the actual error: 
    define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
    Then check /wp-content/debug.log for the error message.

Memory and performance

"Allowed memory size exhausted" during scan

Cause: The initial site scan processes many pages simultaneously and can exceed the default PHP memory limit.

Fix:

  1. Increase the PHP memory limit to at least 256 MB (see above).
  2. Reduce the Max pages per scan setting: go to DPOKit → Settings → Scan → Max pages and lower the value (default: 50; try 20).
  3. If scans still time out, switch to WP-CLI cron instead of WP-Cron: 
    wp cron event run --due-now

Database table issues

"Database tables were not created"

Cause: The database user may lack CREATE TABLE privileges, or the activation hook did not fire (e.g. plugin was activated via WP-CLI without --activate).

Fix:

  1. Go to DPOKit → Settings → Advanced and click Run database setup. This manually triggers the installer.
  2. If the button is not visible, check that your MySQL/MariaDB user has CREATE, ALTER, and INDEX privileges on the WordPress database.
  3. For WP-CLI installations, always use the --activate flag: 
    wp plugin activate dpo-kit

Database upgrade notification on every page load

Cause: A previous upgrade migration was interrupted.

Fix:

Go to DPOKit → Settings → Advanced → Run database setup. If the problem persists, deactivate and reactivate the plugin to trigger the upgrade routine again.

Admin menu and permissions

The DPOKit menu doesn't appear

Cause: Your WordPress user account does not have the manage_options capability.

Fix:

  1. Confirm you are logged in as a user with the Administrator role.
  2. If using a custom role plugin (Members, User Role Editor), ensure the manage_options capability is assigned.
  3. On WordPress Multisite, DPOKit menus appear only on individual sites, not the network admin, unless you have configured network-level access.

"You do not have permission to access this page"

Cause: A security plugin (Wordfence, iThemes Security) or custom functions.php code is restricting admin menu access.

Fix:

  1. Temporarily disable security plugins and check if the menu appears.
  2. Search functions.php and active plugins for remove_menu_page or capability filters targeting manage_options.

Licence activation problems

"Invalid licence key"

Cause: The key was copied incorrectly, or the key belongs to a different environment.

Fix:

  1. Copy the key directly from your customer dashboard — avoid manual typing.
  2. Ensure there are no leading or trailing spaces (paste into a plain-text editor first to strip formatting if needed).
  3. Confirm you are using a pv_live_ prefixed key. Keys prefixed pv_test_ are for staging environments and will not validate on production URLs.

"Site limit reached"

Cause: Your licence tier allows a fixed number of site activations and all slots are used.

Fix:

  1. Go to your customer dashboard → Licences and click Deactivate next to a site you no longer use.
  2. Alternatively, upgrade to Agency tier for unlimited site activations.

Licence API unreachable (staging / local environments)

DPOKit caches the last valid licence response for 7 days. If your server cannot reach the licence API (e.g. no outbound internet from a local dev environment), the plugin continues operating normally during this grace period.

Site URLs containing local, localhost, staging, dev, or test do not consume activation slots.

Plugin conflicts

Consent banner does not appear

Common causes:

CauseFix
Banner status set to PreviewGo to DPOKit → Consent → Banner and set Status to Active
Caching plugin serving a cached pagePurge your cache (WP Rocket, W3 Total Cache, LiteSpeed Cache, etc.) after enabling the banner
Theme or page builder stripping <script> tagsTest with a default WordPress theme (Twenty Twenty-Four) to isolate the conflict
Content Security Policy (CSP) blocking inline scriptsAdd DPOKit's nonce or domain to your CSP script-src directive

Scripts blocked before consent are still loading

Cause: Another plugin or theme is loading scripts outside of WordPress's wp_enqueue_scripts hook, bypassing DPOKit's interception.

Fix:

  1. Use your browser's Network tab to identify which scripts load before consent.
  2. Register those scripts with DPOKit's consent gate using the pv_register_consent_script filter (see Developer Hooks).
  3. As a fallback, add the script domain to DPOKit → Consent → Blocked Domains for header-level blocking.

Conflict with WooCommerce

Ensure you are running WooCommerce 7.0 or later. If WooCommerce cart/checkout pages behave unexpectedly, add their URLs to the Functional consent category exemption list so essential scripts are never blocked:

DPOKit → Consent → Categories → Functional → Exempted URLs

WP-CLI issues

wp dpo-kit commands not found

Cause: WP-CLI was not installed when DPOKit was activated, so the CLI commands were not registered.

Fix:

Deactivate and reactivate the plugin:

wp plugin deactivate dpo-kit && wp plugin activate dpo-kit

Then confirm commands are available:

wp dpo-kit --help

Scan times out when run via WP-Cron

Switch to running scans via WP-CLI for more reliable execution on large sites:

wp dpo-kit scan --max-pages=100

Add this as a system cron job (crontab -e) to run weekly:

0 3 * * 1 /usr/local/bin/wp --path=/var/www/html dpo-kit scan --max-pages=100 --quiet

Multisite issues

DPOKit does not appear on sub-sites

DPOKit must be network-activated from Network Admin → Plugins to appear across all sites. Alternatively, activate it individually on each sub-site.

Settings are not inherited from network level

Network-level policy inheritance is available in Agency tier. Go to Network Admin → DPOKit → Network Settings and enable Enforce network policies on sub-sites. Sub-site administrators can still override settings you leave unlocked.

Still stuck?

  1. Check Tools → Site Health — WordPress surfaces common server misconfigurations there.
  2. Enable WP_DEBUG_LOG and review /wp-content/debug.log for PHP errors.
  3. Review DPOKit's own activity log at DPOKit → Settings → Advanced → View Plugin Log.
  4. Open a support ticket from your customer dashboard and include:
    • WordPress version, PHP version
    • DPOKit version
    • List of active plugins
    • Relevant entries from debug.log