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

# Troubleshooting

Something not working? Most Relyagent issues fall into a handful of buckets. Find the symptom
below, apply the fix, and reconnect the AI client if the fix says to.

**MCP** here is the Model Context Protocol — the standard your AI client uses to reach the
tools Relyagent exposes from WHMCS.

::: tip Turn on more detail first
If a problem is hard to pin down, enable **Verbose Debug Logging** under
**Addons → Relyagent → Settings → General**. It writes extra entries to the WHMCS module log
on every MCP request, then turn it back off when you're done.
:::

## The MCP server stopped responding / clients get 403

**Symptom:** connected clients suddenly can't list or call tools, and requests return
**HTTP 403**.

**Cause:** the MCP server is license-gated. If your Relyagent license is inactive or removed,
the MCP and OAuth endpoints return 403 and no client can connect or call tools.

**Fix:** open **Addons → Relyagent → Settings → License**, confirm the key is present and the
status is active, and renew or re-enter the key if it has lapsed. Service is restored as soon
as the license is active again.

::: 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, don't wait it out.
:::

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

**Symptom:** the AI client shows **"Authorization Failed"** or never finishes connecting.

Work through these in order:

* **Paste all three values.** You must enter the **Client ID** *and* the **Client Secret**,
  not just the Endpoint URL. Admin credentials alone can't connect — the token step requires
  the connection's secret.
* **Confirm the exact Endpoint URL**, character for character:
  `https://<your-whmcs>/modules/addons/relyagent/public/mcp/endpoint.php`
* **Sign in at your WHMCS admin login.** Relyagent uses your normal admin login — no separate
  form — so complete that sign-in when the client redirects you.
* **Approve the consent screen.** The connection isn't authorized until you approve the tools
  it lists.

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

## Tools are missing in the client

**Symptom:** the AI client doesn't see a tool you expected, or calling it is rejected.

Check each of these:

* **Not granted to the connection.** Only ticked tools are listable and callable. Edit the
  connection under **MCP Clients** and tick the tool.
* **The tool's group is off.** A disabled group's tools never list or run. Re-enable the group
  in **Settings → MCP Settings**.
* **It's a dangerous operation.** State-changing tools stay off until you enable
  **Dangerous Operations** in **Settings → MCP Settings** *and* tick the tool on the
  connection.

::: 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

**Symptom:** requests fail with **HTTP 429** and Audit Log rows show **Rate Limited**.

**Fix:** 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

**Symptom:** a **Sync Required** banner, or the **File Integrity** panel flags tampered or
missing deployed files.

**Fix:** open **Settings → Sync** and run **Sync**. Relyagent restores the deployed files to
match its signed baseline; you'll see *"Sync completed successfully."* With **Auto-Sync** on,
a detected mismatch is also resolved automatically on the next admin page load. Learn more on
[File integrity](/relyagent-whmcs/features/file-integrity).

## Update issues

**Symptom:** **Update Now** fails or stays disabled.

Confirm all of these before retrying under **Settings → Update Status**:

* The `modules/addons/relyagent/` directory is **writable** by WHMCS.
* There's enough **free disk space** for the backup and the new files.
* Your **license is active** (Leased keys), or your **Support & Updates** entitlement is active
  (Lifetime keys) — Lifetime installs can run the current version indefinitely, but installing
  a newer one needs active Support & Updates.

Updates back up first and auto-restore on failure, so a failed update leaves your install
untouched. See [Updating](/relyagent-whmcs/updating) and the
[Error reference](/relyagent-whmcs/errors) for the exact messages.

## "ionCube Loader required"

**Symptom:** Relyagent pages print
`ionCube Loader required. Contact support@relyweb.co`.

**Cause:** the release is ionCube-encoded and your server is missing the ionCube Loader or has
one that's too old.

**Fix:** 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 minimum loaders 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 you might see is listed with a plain-English explanation on the
[Error reference](/relyagent-whmcs/errors), and common buyer questions are answered in the
[FAQ](/relyagent-whmcs/faq).
:::