Troubleshooting

This guide covers the most common issues and how to resolve them. If your issue is not listed here, see the support section at the end.

---

Installation and activation

“Plugin could not be activated” or activation error

Check your PHP version. The plugin requires PHP 8.2 or later. Check your PHP version in Tools → Site Health → Info → Server, or ask your host. Most hosts let you switch PHP version from their control panel.

Check your WordPress version. The plugin requires WordPress 6.7 or later. Update WordPress from Dashboard → Updates if needed.

Check file permissions. If you uploaded the plugin by FTP, make sure the plugin folder has the usual permissions (755 for folders, 644 for files).

Database tables were not created. If activation completed without error but features are not working (for example, the Analytics screen says “Download tracking table not found”), deactivate and reactivate the plugin. This re-runs the database setup. If the tables still are not created, check that your database user has permission to create tables.

Setup wizard does not appear after activation

The wizard opens automatically the first time you activate the plugin. If it did not appear, go to Policy Management → Setup Wizard — this menu item stays visible until setup is completed.

Setup runs once. After you finish it, the wizard menu item disappears and every choice it made can be changed under Policy Management → Settings.

---

Documents

A document is not visible to staff

Check the audience. Open the document and look at the Document Settings box. Unless Confidentiality is set to Public, the staff member’s WordPress role must be ticked under Target Audience (Roles) (or no roles ticked at all, which lets any logged-in user read it). The staff member must also be logged in.

Check whether the document is published. Draft and pending documents are not visible to staff. Drafts are labelled “— Draft” in Documents → All Documents.

Check the Document Status. Superseded and Archived documents are retired: they are removed from the Document Hub and search, though they stay reachable by direct link with a status banner. The Status column in Documents → All Documents shows Active, Superseded or Archived. To bring a document back, set its status to Active in the Compliance & Status box.

Check the Effective From date. A published document with a future Effective From date is hidden from staff until that date arrives — they see “Not Yet Effective” at its link. The editor shows a warning when a future date is set. If you meant to schedule an update to an existing document, tick Schedule this update instead, so the current version stays live until the new one takes effect.

Check for pending approval. If Version Approval is switched on, changes made by someone who is not an approver wait in Policy Management → Pending Approvals and are not live until they are approved.

Check page caching. If you use a caching plugin, clear its cache after changing a document’s audience or a user’s role, then ask the user to reload the page.

A document shows an “Access Restricted” message even though the role is in the audience

• Confirm the user’s role is actually ticked under Target Audience (Roles) — a user with several roles needs at least one of them ticked.
• Check the document’s Effective From date (see above).
• If the document is password-protected in WordPress (the Visibility setting in the editor’s Status panel), visitors must enter that password as well. Set Visibility back to Public to rely on the plugin’s audience settings alone.

A document can be found at its URL but is not showing in the Document Hub

Check the Document Status. Superseded and Archived documents are deliberately left out of the Hub and search.

Check the document type. The Hub shows one tab per document type. A document with no type appears under a No document type tab. If a type has no tab, open Settings → Content Management → Manage Document Types and check its Hub Tab setting (edit the type and tick Show as Document Hub tab).

Check the hub shortcode. If your

shortcode has a doc_types attribute, only the document types listed there get a tab. For example, doc_types="policies,procedures" hides a Guide. Add the missing type’s slug (shown under Manage Document Types) to the list.

Try clearing caches. If you use a caching plugin (WP Rocket, W3 Total Cache, LiteSpeed Cache), clear all caches after publishing a document.

---

Acknowledgements

The acknowledgement prompt is not appearing

Check that acknowledgements are switched on. Go to Settings → Features and make sure Enable Acknowledgement System is on.

Check that acknowledgement is required for this document. Open the document in the editor and check that Require acknowledgement is on in the Acknowledgement panel of the editor sidebar.

Check who must acknowledge. In the same panel, the user must belong to one of the Target roles or Target user lists. If none are set, the editor warns that no one will be asked to acknowledge.

Check the user is logged in. Only logged-in users are asked to acknowledge.

Check if the user has already acknowledged. If the user has already acknowledged this version, they see a confirmation instead of the prompt. You can check their record in Policy Management → Acknowledgements.

Check the Document Status. Superseded and Archived documents no longer ask for acknowledgement.

The acknowledgement button is greyed out or disabled

The most common causes:

• The confirmation box is not ticked — the user must tick the “I have read and understood…” box first.
• A comprehension quiz is required — the user must pass the quiz shown on the page before the button unlocks. After too many failed attempts the user must wait for the cooldown period set under Settings → Acknowledgements & Notifications → Comprehension Gate.

• A minimum reading time or reading reach is set (Pro) — the user must keep reading until the requirement is met. A message near the button shows how much reading time is left.

Staff are not receiving reminder emails

Check that WordPress can send email. Many hosting environments block or limit email sent directly by WordPress. Install a transactional email plugin (for example WP Mail SMTP or FluentSMTP) and send a test email.

Check the reminder schedule. Go to Settings → Acknowledgements & Notifications → Reminders & Schedules and confirm Individual document reminder schedule (days before due) is filled in (for example 30, 7, 1). Leaving it blank turns these reminders off.

Check the sender address. Go to Settings → System Configuration → Email Settings and make sure the From Email address is valid for your domain.

Check for an opt-out. Staff can opt out of repeat reminder emails. The first acknowledgement request is still sent to them.

Check overdue reminders. Reminders before the due date are sent on the schedule above. Repeat reminders after an acknowledgement becomes overdue are only sent for documents with a risk rating whose overdue repeat interval is set under Review & reminder cadence by risk tier.

Check that WP-Cron is running. Reminders are sent by scheduled background tasks. If WP-Cron is disabled on your server (common on high-traffic sites), set up a real cron job that calls wp-cron.php regularly. Ask your host or developer.

An acknowledgement was not recorded even though the user clicked the button

1. Ask the user to reload the page and try again. If they saw “Security check failed.”, the page was probably served from a cache with an expired security token.
2. Exclude document pages from page caching for logged-in users (most caching plugins do this by default).
3. Check whether a security plugin or firewall (Wordfence, Sucuri) is blocking requests to admin-ajax.php, which the plugin uses to record acknowledgements. Add an exception if needed.
4. Ask the user to try another browser or a private window, and check the browser console for errors (press F12 and open the Console tab).

---

Approval workflow

The document owner is not receiving approval emails

Work through the reminder-email checklist above to confirm WordPress can send email. Then check:

• Email Notifications is switched on under Settings → Version Approval.
• The document has a Document Owner selected in its Document Settings box.
• That owner title is assigned to a real user under Settings → User Management → Assign a user to each owner title. If no user is assigned, no approval email is sent.

If nobody can approve a change (no owner assigned and no Approver User Roles set), the change is published straight away. If approver roles are set, the change waits in Policy Management → Pending Approvals.

The approval link in the email has expired

Approval links expire after the number of days set in Approval Link Expiry (Days) under Settings → Version Approval (default 30). An expired link shows “This approval link has expired. Please approve from the admin panel.”

To approve, go to Policy Management → Pending Approvals, find the document, and click Approve (or Reject). Preview lets you check the change first.

---

The Document Hub

The hub shows “Document category taxonomy not found” or “Document type taxonomy not found”

The taxonomy the plugin is set to use is not registered. The most common cause is that the slug was changed, or the plugin that registered it was deactivated.

Go to Settings → System Configuration → Post Types & Taxonomies and check Document Type Taxonomy and Document Category Taxonomy. The defaults are document_type and document_category. If another plugin uses the same slug, change either this setting or the other plugin’s taxonomy.

Search is not returning results for documents that clearly match

Check role-based visibility. Search only returns documents the current user is allowed to read. If their role is not in the document’s audience, it never appears in their results, however good the match.

Check whether the document is published and Active. Drafts, documents awaiting approval, future-dated documents, and Superseded or Archived documents do not appear in search.

Check that the user is logged in. By default, search requires a logged-in user. To let logged-out visitors search Public documents, switch on Allow anonymous access under Settings → Search → Public REST API Access. Also check that Hide from logged-out visitors is off if you want guests to find Public documents.

Wait and retry. Recent searches are cached in the browser for up to 5 minutes. If you have just published or changed a document, reload the page and search again.

The hub tabs show no documents even though documents exist

Check the doc_types attribute on the

shortcode. It lists document type slugs — find them under Settings → Content Management → Manage Document Types. Without the attribute, the hub shows the Policies, Procedures, Guides and Forms types; if none of the listed slugs match, it shows every document type instead.

---

PDF exports

PDF download fails or the file is blank

PDF generation is built into the plugin — there is nothing extra to install.

1. If the download says “Invalid download request.”, the page was served from a cache with an expired link. Reload the page (or clear your page cache) and try again.
2. If it says “PDF generation is not available”, the plugin’s files may be incomplete. Delete and reinstall the plugin (your data is kept by default — see Privacy & Data Management) and try again.
3. If PDFs are blank or cut off, check your server has enough memory. Large documents can need more than the default PHP memory limit; ask your host to increase it.

---

Analytics

New document views are not appearing in Analytics

Views are collected in batches and added to the reports about once an hour, so a view can take up to an hour to show. If nothing appears after a couple of hours, check that WP-Cron is running (see Staff are not receiving reminder emails above). For more analytics issues, see Analytics & Search Data.

Old search or view records are still there after I shortened the retention window

The clean-up that enforces retention runs once a week. To delete the data straight away, use Settings → System Configuration → Maintenance → Data Management.

🔒 Pro feature — requires the Pro plugin.

Pro add-on features

Each Pro guide has its own troubleshooting section:

• Document Compliance, evidence packs and scheduled reports — see Per-Document Compliance Dashboard.
• Webhooks not arriving or failing signature checks — see Outbound Acknowledgement Webhooks.
• Approval chain emails, skipped stages and “Too many attempts” — see Multi-Stage Approval Workflow.
• Frameworks, Coverage & Gaps, auto-fetch, briefs and the Compliance Audit — see Regulatory Framework Mapping.

If a Pro screen shows This is a Pro feature, your licence is not active — go to Settings → Licence.

---

General performance

The plugin is slowing down my site

Enable caching. Use a page caching plugin. The plugin works with all major caching plugins.

Check the analytics retention. Very large search or view logs can slow down the database. Go to Settings → System Configuration → Analytics & Data Retention, set a shorter retention window, and purge old data from Maintenance → Data Management on the same tab.

Turn off logging you do not use. If you do not use the search reports, switch off Enable Search Logging. Leave Track PDF Downloads off unless you need it.

---

Getting support

If your issue is not covered here:

• Support forum — Post in the plugin’s Support forum on WordPress.org. Include your WordPress version, PHP version, and a description of what you expected versus what happened.
• Pro support — Pro add-on customers can contact Dantian directly for support.

When reporting an issue, it helps to include:

1. Your WordPress version and PHP version
2. Which other plugins are active (deactivate others temporarily to test for conflicts)
3. Any error messages shown on screen or in the browser console
4. Steps to reproduce the issue