Troubleshooting

Find your symptom and work the steps in order. For a specific message, check the Error reference first.

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).

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.

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"

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.

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

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

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.

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).

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

"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.

Still stuck?

Every message is listed on the Error reference, and common questions are answered in the FAQ.