HexaHost-GameCloud/docs/integrations/whmcs/troubleshooting.md

WHMCS troubleshooting

Common integration failures between WHMCS and HexaHost GameCloud.

Diagnostic tools

Tool	Location
WHMCS module log	Utilities → Logs → Module Log
GameCloud addon dashboard	Addons → HexaHost GameCloud
API health	GET https://api.example.net/api/v1/health/live
OpenAPI	/api/v1/docs — API README
Reconciliation	Addon → Reconciliation tab

Authentication errors

Invalid signature / 401

• Confirm WHMCS_API_SECRET matches exactly on both sides (no trailing newline)
• Check WHMCS_INTEGRATION_ID matches addon Integration ID
• Verify server clock (NTP): X-HGC-Timestamp skew > 5 min fails
• Ensure GameCloud API URL has no trailing slash

mTLS / certificate errors

• INTEGRATION_MTLS_ENABLED=true but fingerprint not registered → register in addon mTLS tab
• Wrong CA bundle on WHMCS → point to GameCloud CA PEM
• Reverse proxy not forwarding X-HGC-Client-Cert-Fingerprint → see mtls

Provisioning failures

CreateAccount returns error string

1. Read WHMCS module log full message
2. Common causes:
   • Invalid plan slug — fix product mapping
   • Catalog plan inactive
   • No eligible game node (NO_NODE_AVAILABLE)
   • Invalid Minecraft version for software family

Server stuck Pending in WHMCS

• GameCloud provision may have succeeded — check addon dashboard service count
• Run reconciliation dry-run
• Manual SSO to panel to verify server exists

Lifecycle sync

Suspend / unsuspend not applied

• WHMCS module action failed silently — check module log
• GameCloud worker backlog — check Redis / worker logs
• Event poll not running — verify WHMCS cron active

Terminate left data on node

• Terminate API may have failed mid-flight — admin force-terminate in panel
• Node offline during terminate — retry when node ONLINE

SSO issues

See dedicated SSO guide. Typical fixes:

• APP_URL mismatch between GameCloud and expected redirect
• Clock skew
• Service not linked to correct externalServiceId

Usage billing gaps

• Usage export cron not running
• Mismatch between WHMCS service ID and GameCloud external ID — reconciliation

Network

# From WHMCS host
curl -v https://api.example.net/api/v1/health/live
openssl s_client -connect api.example.net:443 -servername api.example.net

Firewall must allow outbound 443 from WHMCS to GameCloud API.

Enable debug logging

WHMCS: enable module debug in System Settings → General Settings (temporarily).

GameCloud: set LOG_LEVEL=debug on API, reproduce, revert to info.

Escalation data to collect

• WHMCS service ID and timestamp of failure
• Module log entry (redact secrets)
• GameCloud request ID from API response header if present
• Integration ID and API version

Related

• Security
• Configuration
• Incident response
• Reconciliation