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.

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.

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"

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.

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.

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.

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.

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.

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 and the Error reference for the exact messages.

"ionCube Loader required"

Symptom: Relyagent pages print ionCube Loader required. Contact [email protected].

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.

Still stuck?

Every message you might see is listed with a plain-English explanation on the Error reference, and common buyer questions are answered in the FAQ.