---
title: "Troubleshooting"
description: "The most common WHMCS module failures and how to fix them. Test connection errors, invalid keys, missing member groups, product changes rejected by the panel and reseller lifecycle actions that require a manual step."
---

Most module failures fall into a handful of categories: an invalid or mis-typed token, a missing product config option, a legitimate limitation of the panel API surfaced as an actionable error, or a network issue between WHMCS and the panel. This page covers each of those with the exact message you will see, the cause behind it, and the concrete steps to resolve it.

The single most useful thing to read when something goes wrong is the module log. WHMCS records every panel call the module makes in its native `tblmodulelog` table, and the addon exposes that view under **Addons → Xtream AI Panel → Module Logs**. Tokens are never written there; the log is safe to share with support or to keep open in another tab while you debug.

## Test Connection errors on a panel entry

These fire from the **Test Connection** button on the panel form, either in the list view or in Add Panel / Edit Panel.

| Symptom | Cause | Fix |
|---|---|---|
| `Panel authentication failed.` | The token is invalid, revoked, expired, or was mis-copied. | Open your Xtream AI Panel, go to **Settings → Panel API Keys**, and verify the prefix in the list matches the first 20 characters of the token you pasted. If the key is deleted or expired there, create a new one. If the prefix matches but the test still fails, the secret half was mis-copied; rotate the key to regenerate the secret and paste the full new token. |
| `Could not reach the panel.` | DNS is wrong, the panel is offline, or your WHMCS host cannot reach the panel over HTTPS. | Verify the API URL. From a shell on the WHMCS host, run `curl -sSf https://<your-panel-domain>/panel-api/v1/health`. It should print `{"status":"ok","version":"v1"}`. If it prints anything else, the issue is DNS, firewall or the panel itself, and it is worth resolving there before continuing. |
| A TLS-related message (`SSL certificate problem`, `Peer certificate cannot be authenticated`). | The panel's TLS certificate is expired, self-signed, or issued for a different hostname. | Fix the certificate on the panel side. Only disable Verify SSL as a temporary workaround, and only when you know why the certificate is invalid. Disabling Verify SSL is not appropriate for production; a valid certificate is. |
| `Panel URL is required.` or `API key is required.` | You clicked Test Connection with one or both fields empty. | Fill both fields and click Test again. |
| `The panel is temporarily unavailable.` | The panel returned HTTP 503, usually during a restart or a heavy operation. | Retry after a few seconds. The connection test has no side effects. |

## CreateAccount errors

These fire when a paid order transitions to Active and the module attempts to provision the panel line or sub-reseller.

| Symptom | Cause | Fix |
|---|---|---|
| `Connection successful.` on Test Connection but `The panel rejected the request.` at CreateAccount on a Sub-Reseller product. | The product's **Sub-Reseller Member Group** id is missing, or it points at a group that does not exist on the panel. | Open **Products/Services → your product → Module Settings** and set **Sub-Reseller Member Group** to a valid numeric id. You can find valid group ids on your panel under **Reseller settings → Member groups**. Save the product, then re-run CreateAccount from the WHMCS service page. |
| `Admin key requires field 'member_id'` or a similar body-validation error. | The panel entry's Key type is set to Admin but the token is actually a reseller token, or the Admin owner member_id field is empty. | Edit the panel entry. If the token is a reseller token, switch Key type to **Reseller** and clear the Admin owner member_id. If the token is genuinely an admin token, fill Admin owner member_id with the numeric id of the reseller that should own the lines. |
| `A client email address is required to provision a Sub-Reseller account.` | The WHMCS client on the order has no email address on their profile. | Open the client's profile in WHMCS and add an email. Sub-Reseller accounts require an email on the panel side; the module refuses to proceed without one rather than posting a partial record. |
| `The reseller does not have enough credits or user slots.` | The panel account behind the key is out of credits (credits mode) or has reached its user cap (users mode). | Top up the account on the panel. If the key is a reseller key, contact your provider. If the key is your admin key, adjust the reseller's balance from the panel's Users section. Re-run CreateAccount after the balance is topped up. |
| `No package selected for this product.` | The product's Module Settings tab does not have a Package chosen. | Open the product, go to Module Settings, pick a Package from the dropdown, and save. |
| `No panel found. Add and activate a panel in Addons → Xtream AI Panel.` | The panel dropdown on the product is empty, or every panel entry is inactive. | Add or reactivate a panel entry in **Addons → Xtream AI Panel → Panels**, then set the Panel dropdown on the product. |
| `Stored API token could not be decrypted. Re-enter the access key for this panel.` | The WHMCS `encrypt()` key has changed (a `configuration.php` restore from a different install, for example), so the token stored on the panel entry can no longer be decrypted. | Edit the panel entry, paste the token again, Test Connection, and save. |

## Suspend, Unsuspend and Terminate errors

These fire from the WHMCS service page or from automated dunning actions.

| Symptom | Cause | Fix |
|---|---|---|
| On a Sub-Reseller product: `The panel API does not support changing a reseller status. Please disable this account manually from the panel and try again.` | The panel API does not expose a reseller status field yet. See [Provisioning Modes](/docs/?page=whmcs-module-provisioning-modes). | Log in to your panel, disable (or delete, for Terminate) the reseller account manually from **Users**. The WHMCS to panel link stays intact so you can retry the action safely once the panel is in the desired state. Nothing is lost by the failed attempt. |
| `This service has no panel line yet. Provision it first.` | The service was moved to Suspended or Terminated before CreateAccount ran successfully. There is nothing on the panel to disable or delete. | Re-run CreateAccount from the service page (Module Commands → Create). If CreateAccount also fails, resolve that first; see the CreateAccount section above. |
| `Panel authentication failed.` on a Suspend that used to work. | The token was rotated or revoked on the panel side since the last successful call. | Rotate the key on the panel, edit the panel entry with the new token, Test Connection, save. Retry Suspend. |

## Renew errors

These fire when a renewal invoice is paid, or when an admin runs a manual renewal.

| Symptom | Cause | Fix |
|---|---|---|
| `No package selected for renewal.` | The product's Package option is empty. This can happen after a product was edited without re-saving Module Settings. | Open the product, go to Module Settings, pick a Package, and save. |
| Credits mode: `The reseller does not have enough credits or user slots.` on renewal. | The account behind the key is out of credits at renewal time. | Top up the account, then retry the renewal from the WHMCS invoice page. Renewals are idempotent by way of the invoice; retrying does not double-charge the reseller. |
| The renewal succeeded but WHMCS's next due date did not move. | The WHMCS billing cycle is set to `One Time` or `Free`, so the module deliberately skips the `nextduedate` write. | Set the product to a recurring cycle that matches the panel package duration. |

## ChangePackage errors

These fire when an operator switches a service to a different WHMCS product.

| Symptom | Cause | Fix |
|---|---|---|
| `Package changes on an existing line are not supported by the panel API. Please terminate and re-provision.` | The new WHMCS product points at a different panel `package_id`. The panel API does not accept `package_id` on `POST /lines/{id}/update`. | Terminate the current service (which deletes the line on the panel) and create a fresh order for the new product. The new order provisions a new line with new credentials on the new package. |
| `Package changes are not supported for Sub-Reseller products.` | You attempted a product change on a Sub-Reseller service. | Sub-Reseller accounts do not have a package concept. If you need to change the credit topup amount or the member group, edit the current product's Module Settings; a new WHMCS product is not required. |

## Client area errors

These are what the customer might see on their own service page.

| Symptom | Cause | Fix |
|---|---|---|
| `Your IPTV line is not ready yet.` | The CreateAccount hook has not completed. Either it is still running, or it errored out. | Check the **Module Logs** tab for the last `create` entry on this service. If the entry is missing or shows an error, re-run CreateAccount from the service page (Module Commands → Create). |
| The card renders but Active Connections shows `Failed to load.` | The browser-side call to fetch active connections failed, usually because the panel entry lost connectivity between the initial page render and the connections fetch. | Refresh the client area page. If the failure persists, verify the panel connection with Test Connection in the addon. |

## Where module output lives

Two places carry the diagnostic information you need.

**WHMCS Module Log.** The addon's **Module Logs** tab surfaces WHMCS's native module log filtered to this module. Each row shows:

- **Date**: when the call was made, in the WHMCS time zone.
- **Server / Service**: the WHMCS service id and the panel entry id.
- **Action**: the lifecycle hook (`create`, `suspend`, `unsuspend`, `renew`, `change_password`, `terminate`, `sync`, `change_package`).
- **Request summary**: a short line describing the intent (never the token, never the customer's password).
- **Response summary**: what the panel returned. On success, a short OK. On failure, the friendly error message the module surfaced, plus the panel's own detail if it provided one.

**WHMCS Activity Log**. WHMCS's global activity log picks up module failures that reached the operator UI. Useful for correlating a module failure with the exact admin who triggered it.

Tokens are never rendered in either log. If a panel error message happens to contain the token (rare, but possible with third-party proxies), the module replaces the token with `***` before logging or displaying.

## Where to go if none of the above matches

If you have exhausted this page and the failure is still unexplained, the shortest path to a resolution is:

1. Open **Module Logs** and copy the last few rows for the affected service.
2. Reproduce the failure with Test Connection on the panel entry, and note the exact message.
3. Confirm the panel is reachable from the WHMCS host with `curl https://<your-panel-domain>/panel-api/v1/health`.
4. Open an issue on the [module's GitHub repository](https://github.com/Xtream-AI/whmcs-xtreamai/issues) with the module version (visible on the addon's Dashboard tab), your WHMCS version, your PHP version, and the log excerpt. The tokens are already redacted; nothing in the log is a secret.

## See also

- **[Configure](/docs/?page=whmcs-module-configure).** The end-to-end setup flow. Most CreateAccount failures trace back to a missing or wrong config option.
- **[Reseller vs Admin Keys](/docs/?page=whmcs-module-key-types).** Which features are unreachable on a reseller key and where the "admin only" errors originate.
- **[Provisioning Modes](/docs/?page=whmcs-module-provisioning-modes).** Exact panel calls per lifecycle hook, per mode. Reading it once makes every "why did this fail" question easier to answer.