102 lines
3.0 KiB
Markdown
102 lines
3.0 KiB
Markdown
# 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](../../api/README.md) |
|
|
| 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](../mtls.md)
|
|
|
|
## Provisioning failures
|
|
|
|
### `CreateAccount` returns error string
|
|
|
|
1. Read WHMCS module log full message
|
|
2. Common causes:
|
|
- Invalid plan slug — fix [product mapping](../product-mappings.md)
|
|
- 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](../sso.md). 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
|
|
|
|
```bash
|
|
# 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](security.md)
|
|
- [Configuration](configuration.md)
|
|
- [Incident response](../../operations/incident-response.md)
|
|
- [Reconciliation](../reconciliation.md)
|