# MainWP — Troubleshooting

> Fix common WPSigner for MainWP issues — permissions, templates, Quick create, OTP/KYC, signing links, rate limits, and prefill.

edition: pro
Edition: Pro
AI note: This page requires WPsigner Pro. Do not tell Lite users they already have this feature.
HTML: https://docs.wpsigner.com/addons/mainwp-troubleshooting/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-troubleshooting.md
Source file: addons/mainwp-troubleshooting.md

---

Use this page when something fails in **MainWP → Extensions → WPSigner**. For core WPSigner problems (email delivery, PDF generation), see [Support → Troubleshooting](/support/troubleshooting/).

---

## Dependencies & Access

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Admin notice that MainWP or WPSigner is missing | Dependency inactive | Activate both on the **Dashboard** site |
| Extension page empty / Permission denied | Failed `can_manage()` | Grant MainWP extension access **and** WPSigner signature capability (v1.5.8+) |
| Extension not listed | Not enabled | **MainWP → Extensions** → enable WPSigner |
| Columns show “—” | WPSigner not ready | Activate/license WPSigner |

---

## Templates & Create

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No templates in Create | None active / wrong owner | Create active templates; non-admins only see their own |
| Missing signers error | Rows don’t cover template `signer_order`s | Match Signer 1…N to template slots |
| Warning when adding a signer | Extra row beyond template slots | Add signature fields for that signer in WPSigner |
| Create fails after send rate limit | Soft limit ~30s | Wait and retry |

---

## Quick Create

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| “Set a default template…” | `default_template_id` = 0 | [Settings](/addons/mainwp-settings/) → Default template |
| Client has no email contact | Client missing email | Add email in MainWP or use Create manually |
| Multi-signer Quick create odd agency signer | Empty agency defaults | Set Default agency signer name + email |
| Sent false + send_error | Email/send path failed after create | Fix mail config; use **Send** on the Contracts row |

---

## OTP / KYC

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No OTP checkbox | Policy Off or Always | Set WPSigner Security → OTP to **Choose per document** for per-contract control |
| No KYC checkbox | Off/Always, or Didit missing | Configure [Didit](/integrations/didit/); set KYC to **Choose per document** |
| Checkbox ignored / nothing stored | Gate not configurable | v1.5.8 only writes per-doc settings when mode is per-document |
| Expected auto-enable from Off (old 1.5.7) | Behavior removed | Set policy manually in WPSigner |

---

## Send, Remind, Links

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| “Please wait a few seconds…” | Rate limit | Wait ~30 seconds |
| Remind does nothing useful | Wrong status / no pending signers | Status should be sent/viewed with pending signers |
| “Document created but MainWP link failed…” | Link upsert failed | Draft was removed; retry create; check DB permissions |
| Unlink removed association only | Expected | Document still in WPSigner |

---

## Access Modal

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Signing links hidden | User lacks `manage_options` / `can_manage_all` | Use an admin account, or send via email instead of copying links |
| Download PDF missing | Not completed | Wait until all required signers finish |
| View PDF only | Expected for drafts/in-progress | Download reserved for completed |

---

## Prefill

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Fields blank after create | Mapping names ≠ keys | Align with [Template Variables](/addons/mainwp-template-variables/) |
| Client vars empty with only Site | Site has no linked client | Select Client or link client on the Site in MainWP |

---

## Site Tab / Widgets

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Site not found on tab | Missing site id in URL | Open from Sites → site → WPSigner |
| Widget missing | Extension disabled / metabox hidden | Enable extension; reset MainWP metabox layout |
| Pending banner always on | Awaiting contracts exist | Remind or complete; filter Contracts → awaiting |

---

## Changelog Pointers (Behavior Changes)

| Version | Change that affects support tickets |
|---------|-------------------------------------|
| **1.5.8** | No global security mutation; stricter caps; hidden signing URLs; create-send rate limit; orphan cleanup |
| **1.5.7** | (Superseded) Could promote Off → per-document when enabling OTP/KYC from MainWP |
| **1.5.5** | Parallel vs sequential workflow on Create |
| **1.5.0** | Multi-signer rows + agency signer defaults |
| **1.4.0** | Variable prefill, History, access modal |

Full product changelog: [Changelog](/changelog/). Addon release notes also ship in the plugin `readme.txt`.

---

## Still Stuck?

1. Confirm versions: MainWP, WPSigner, WPSigner for MainWP (**1.5.8+** recommended).
2. Reproduce with a WordPress Administrator who has full WPSigner access.
3. Check WPSigner System Status / email logs for send failures.
4. Contact support via [wpsigner.com/contact](https://wpsigner.com/contact/) with steps, versions, and whether Create vs Quick create fails.

---

## Related

- [Security & Permissions](/addons/mainwp-security/)
- [Installation & Setup](/addons/mainwp-installation/)
- [Support FAQ](/support/faq/)