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