Skip to main content

Troubleshooting

Connection to Mautic shows "failed" or "connected with issues"​

Check the status screen: it reports the Mautic version detected, lists any missing or non-writable fields, and shows the time of the last check.

  • Confirm the Mautic URL has no trailing slash and includes http:// or https://.
  • Confirm the Mautic version is 7.1.3 or later, or 7.2.x. Versions 7.1.0 through 7.1.2 have a known bearer token bug in the API v2 endpoints WHMAUTIC uses.
  • Re-run the check from Settings → Diagnostics, which tests the saved configuration without writing anything.

OAuth2 returns invalid_client or a 500 error​

  • The Client ID is the OAuth2 client identifier, in the format <id>_<random>. Entering only the random part returns invalid_client.
  • An OAuth2 client created outside the Mautic UI (directly in the database, or through the console) can be missing its role and user link. The token is issued, but every API call then fails with 500. Create the client through the Mautic UI to avoid this.

See Mautic Configuration for the full setup.

The queue is not moving​

  • Confirm the WHMCS cron (cron.php) runs on schedule: the worker that drains the queue only runs when the cron runs.
  • Check the status screen for the last cron run time, and for a stopped versus empty queue: these are different states.
  • An item stuck in processing is requeued automatically after 15 minutes, so one stuck item does not block the rest of the queue indefinitely.

A client did not reach Mautic​

Open the activity screen and search by client, email or event. Each row shows status and number of attempts. A failed item is retried up to 5 times, with increasing waits (1, 5, 15, 60 and 240 minutes), before it is marked as a definitive failure.

A segment is missing, or was not removed from a contact​

  • WHMAUTIC only manages segments it created through its own mapping screens. A segment added by hand in Mautic (a form, a campaign) is never removed, by design.
  • If WHMAUTIC cannot read a contact's current segments from Mautic, reconciliation aborts without removing anything, so a temporary API failure never strips existing segments. Check the connection status and retry.

See Segment Mapping for the full reconciliation rule.

The admin panel is in the wrong language​

The panel follows the WHMCS administrator's language setting. Change the administrator's language in WHMCS: there is no separate switch inside WHMAUTIC. A missing translation falls back to English. See Languages.