WHMCS Addon Not Working? 8 Fixes That Actually Solve It (2025)
You installed a WHMCS addon, activated it in admin, and now it is not working. Maybe the addon menu is missing, maybe you see an Oops error, or maybe provisioning does not execute after payment. This is one of the most common WHMCS admin issues, and in most cases the fix is straightforward.
This guide covers eight common root causes and the exact steps to fix each one quickly.
Fix 1 — Check file upload location
The most common cause is wrong module path. Addon modules should be in /modules/addons/ under your WHMCS root. The addon folder and main PHP filename should match the module name exactly, including case on Linux servers.
Example expected structure:
/path/to/whmcs/modules/addons/myiptv/myiptv.phpIf the path or filename is off, WHMCS will not detect it.
Fix 2 — Check admin role permissions
Even when installed correctly, an addon may not appear for your admin role. In WHMCS admin, open Setup > Addon Modules, click Configure, and confirm your role has access in Access Control.
This is the most common cause of the "WHMCS addon not showing in menu" issue.
After saving, reload the admin panel and re-check Addons menu visibility.
Fix 3 — Check WHMCS version compatibility
If the addon worked before and broke after a WHMCS upgrade, compatibility is likely the issue. Check Activity Log for module-related errors and compare your WHMCS version against developer docs.
Typical symptoms include Oops pages, blank screens, or disabled module actions.
Fix 4 — Verify ionCube Loader version
Many paid modules are ionCube-encoded. Outdated loader versions can break encoded files and throw decode errors.
Update ionCube loader from EasyApache (cPanel/WHM) or server package level, then restart PHP-FPM/Apache and retest.
Fix 5 — Correct file permissions
Wrong permissions can block WHMCS from reading or executing addon files.
- Directories:
755 - PHP files:
644
Avoid 777; it creates security risk and is not a proper fix.
Fix 6 — Resolve PHP version conflicts
Some older modules fail on newer PHP versions due to deprecated/removed functions. Compare your server PHP with module requirements.
If mismatch exists, either update the module or switch WHMCS runtime to compatible PHP temporarily.
Fix 7 — Detect hook conflicts
Two modules hooking the same event can conflict and cause random failures. Enable hooks debug mode, reproduce the issue, then inspect logs for competing hook files or stack traces.
Disable other addons one by one to isolate the conflict source.
Fix 8 — Re-upload clean files
Interrupted FTP uploads or bad extraction can produce partial/corrupt module files. Re-download from original source, remove old addon directory, upload clean files, and activate again.
Before reinstalling, record your module settings so you can reapply them.
Quick diagnostic checklist
| Check | Common Symptom | Fix |
|---|---|---|
Module path: /modules/addons/{name}/{name}.php | Addon not showing | Re-upload to correct path |
| Admin role access | Missing in Addons menu | Configure Access Control |
| WHMCS/module compatibility | Oops page | Use supported version |
| ionCube version | Decode errors | Update loader |
| Permissions 755/644 | Permission denied | Fix chmod via panel/SSH |
| PHP compatibility | Fatal errors | Switch PHP or update addon |
| Hook conflicts | Random/partial failures | Debug and isolate conflicting addon |
| File integrity | Inconsistent behavior | Re-download and clean upload |
Still not working?
If all eight checks fail, open a support ticket with the module vendor and include your WHMCS version, PHP version, ionCube version, and exact log error. This context dramatically reduces resolution time.
Internal resources
Prevent future addon failures
Use staging for every new addon, track tested WHMCS/PHP versions, and always back up before upgrades. Compatibility checks before updating WHMCS prevent most outages.
Frequently asked questions
Why is my WHMCS addon not showing in the menu?
The most common reason is that your admin role was not granted access during module configuration. Go to Setup > Addon Modules > Configure and verify Access Control for your role.
How do I fix the WHMCS Oops error on an addon?
An Oops error usually means addon incompatibility with your WHMCS version or an outdated ionCube Loader. Check Activity Log for the exact error and compare your current stack with module requirements.
What file permissions should WHMCS addon files have?
Use 755 for directories and 644 for PHP files. Avoid 777 because it introduces security risks and is not a proper long-term fix.
Conclusion
A WHMCS addon not working is usually caused by one of eight issues: wrong path, missing access permissions, version mismatch, ionCube problems, permission errors, PHP conflict, hook conflict, or incomplete upload. Work through this checklist and most problems resolve quickly.
