---
url: /relyagent-whmcs/troubleshooting.md
description: >-
  Fixes for the most common Relyagent problems — Access Denied, license-only
  pages, clients getting 403, "Authorization Failed", missing tools, rate
  limiting, file-integrity flags, update failures and the ionCube Loader error.
---

# Troubleshooting

Find your symptom and work the steps in order. For a specific message, check the [Error reference](/relyagent-whmcs/errors) first.

::: tip Turn on more detail first
For hard-to-pin-down problems, enable **Verbose Debug Logging** under **Addons → Relyagent → Settings → General**. It writes extra WHMCS module-log entries on every MCP request; turn it back off when done.
:::

## The addon page is blank, shows only the license field, or "Access Denied"

* **Admin permissions:** verify your role has access to Relyagent under **Configuration → System Settings → Administrator Roles**.
* **License activation:** Relyagent shows only **License Information** until an **Active** key is configured. Validate or renew the key under **Settings → License Information** (see [Licensing](/relyagent-whmcs/licensing)).

## The MCP server stopped responding / clients get 403

Connected clients suddenly can't list or call tools and requests return **HTTP 403**.

The MCP server is license-gated. Open **Addons → Relyagent → Settings → License Information**, confirm the key is active, and renew or re-enter it if lapsed. Service is restored as soon as the license is active.

::: info A brief licensing outage won't cause this
The license check runs locally on the request path, so a short outage of our licensing server does **not** interrupt a working install. A persistent 403 means the license itself is inactive — renew it.
:::

## An AI client won't connect / "Authorization Failed" {#authorization-failed}

The AI client shows **"Authorization Failed"** or never finishes connecting. Work through in order:

1. **Supply all credentials:** provide the **Client ID**, **Client Secret**, and **Endpoint URL** (the token endpoint requires the secret).
2. **Verify URL:** confirm the endpoint matches exactly:
   ```
   https://<your-whmcs>/modules/addons/relyagent/public/mcp/endpoint.php
   ```
3. **Authenticate:** sign in via the native WHMCS admin login prompt.
4. **Grant consent:** approve the tool list on the consent screen to finalize authorization.

Grab the Endpoint URL and credentials from **Addons → Relyagent → MCP Clients**; see the per-client [Setup guides](/relyagent-whmcs/guides/claude-desktop).

## Tools are missing in the client

| Cause | Fix |
| --- | --- |
| Not granted to the connection | Edit the connection under **MCP Clients** and tick the tool |
| The tool's group is off | Re-enable the group in **Settings → MCP Settings** |
| It's a dangerous operation | Enable **Dangerous Operations** in **Settings → MCP Settings** *and* tick the tool |

::: warning Adding a tool needs a reconnect
Removing a tool applies immediately, but **adding** a tool requires the client to reconnect and re-consent. See [Connections & OAuth](/relyagent-whmcs/features/connections-oauth).
:::

## Rate limited / HTTP 429

Requests fail with **HTTP 429** and Audit Log rows show **Rate Limited**. Raise the caps under **Settings → MCP Settings** — **Calls / minute** (default 60) and **Calls / day** (default 5000), both per token. See [audit and rate limits](/relyagent-whmcs/features/audit-and-rate-limits).

## File-integrity issues

If **Sync Required** appears or file tampering is flagged:

1. Open **Settings → Sync** and click **Sync** to restore files to the signed baseline (*"Sync completed successfully."*).
2. Enable **Auto-Sync** to automatically correct drift on admin page load (see [File integrity](/relyagent-whmcs/features/file-integrity)).

## Update issues

**Update Now** fails or stays disabled. Confirm all of these before retrying under **Settings → Update Status**:

* **Directory permissions:** ensure `modules/addons/relyagent/` is writable by WHMCS.
* **Disk capacity:** verify sufficient disk space for backups and extraction.
* **Entitlement status:** confirm an active Leased license or active Support & Updates for Lifetime keys.

Updates back up first and auto-restore on failure. See [Updating](/relyagent-whmcs/updating) and the [Error reference](/relyagent-whmcs/errors).

## "ionCube Loader required"

Relyagent prints `ionCube Loader required. Contact support@relyweb.co`. The release is ionCube-encoded and your server is missing the loader or has one too old.

Ask your host to install/enable the ionCube Loader (13.0.2+ on PHP 8.2, 14.4.0+ on PHP 8.3). WHMCS's own minimums already satisfy this, so this usually means the loader isn't enabled for the PHP version WHMCS runs on. See [Requirements](/relyagent-whmcs/requirements).

::: tip Still stuck?
Every message is listed on the [Error reference](/relyagent-whmcs/errors), and common questions are answered in the [FAQ](/relyagent-whmcs/faq).
:::