Troubleshooting

This page covers the most common issues encountered when installing, configuring, or using HmSingleOrderAddon.

---

Installation Issues

The addon doesn’t appear in Addon Modules

Cause: The files are not in the correct location or have incorrect permissions.

Fix:

1. Verify the addon folder is at modules/addons/HmSingleOrderAddon/ (not nested one level deeper)
2. Ensure there is a file named HmSingleOrderAddon.php directly inside the folder
3. Set directory permissions to 755 and file permissions to 644
4. Clear WHMCS caches under Utilities → System

Activation fails with a database error

Cause: The MySQL user doesn’t have CREATE TABLE permissions.

Fix: Grant CREATE, ALTER, DROP, and INDEX privileges to the WHMCS database user, run the activation again, then revoke DROP if desired.

---

License Issues

”License key not found” error on the checkout page

Cause: The license key wasn’t saved correctly, or it contains extra spaces.

Fix:

1. Go to System Settings → Addon Modules → HmSingleOrderAddon → Configure
2. Clear the License Key field, paste the key fresh (avoid copying trailing spaces)
3. Save and try the checkout page again

”Domain not authorized” error

Cause: The license is registered to a different domain than your WHMCS URL.

Fix: Log in to your HostModules client portal and update the allowed domain on your license, or contact support.

Checkout works on staging but fails on production with license error

Cause: The production domain isn’t authorized for the license.

Fix: Add your production domain to the license in your client portal. You can authorize multiple domains if you have staging + production.

---

Checkout Page Issues

The default WHMCS order form still appears instead of the new one

Cause: The order form template wasn’t set to HmSingleOrderForm during activation.

Fix:

1. Deactivate and reactivate the addon
2. Or manually update the WHMCS setting: System Settings → General Settings → Ordering → Order Form Template → select HmSingleOrderForm

Styling is broken / CSS not loading

Cause: The template CSS hasn’t been compiled or the path is wrong.

Fix:

1. Run npm install && npm run build inside templates/orderforms/HmSingleOrderForm/
2. Check that css/hm-main.css exists and has a non-zero file size
3. Check your browser console for 404 errors on CSS file paths
4. Verify the WHMCS $WEB_ROOT variable is set correctly (should be your WHMCS URL)

Domain availability search doesn’t work

Cause: No domain registrar is configured, or the registrar API isn’t responding.

Fix:

1. Go to System Settings → Domain Registrars and ensure a registrar is active
2. Test the registrar by adding a domain manually via the WHMCS admin
3. Check Utilities → Logs → Module Log for registrar API errors

Payment gateway fields don’t appear

Cause: No payment gateways are active for the customer’s currency, or the gateway module has an error.

Fix:

1. Go to Payments → Payment Gateways → Manage Existing Gateways and ensure at least one gateway is active
2. Check gateway configuration for API key errors
3. Review Utilities → Logs → Gateway Log for errors

---

After Order Placement

Order is stuck in “Pending” status

Cause: The WHMCS cron job isn’t running, or payment wasn’t received.

Fix:

1. Verify the WHMCS cron job is running: Utilities → Cron Log
2. Check the invoice for the order — if it shows “Unpaid”, the payment wasn’t captured
3. Review the Gateway Log for payment processing errors

Customer didn’t receive a confirmation email

Cause: WHMCS email delivery issue or the email template is disabled.

Fix:

1. Check System Settings → Email Templates — ensure the “Order Confirmation” template is active
2. Check Utilities → Email Log for delivery failures
3. Verify WHMCS SMTP settings under System Settings → Email

---

Getting Support

If you can’t resolve an issue using this documentation:

1. Check the debug output — enable Debug Mode and include the output in your support request
2. Collect logs — WHMCS Module Log, Gateway Log, and PHP error log
3. Contact support at hostmodules.com/support with the above information

Typical support response time is within 1 business day.