Connection Issues

If the plugin cannot connect to your Mautic instance, you will see errors when using the Test Connection button or when any module tries to sync data. Below are the most common connection problems and how to fix them.

API Not Enabled in Mautic

Symptom: The Test Connection button returns an authentication error or a 403 Forbidden response.

Solution: The Mautic API is disabled by default. You must enable it manually.

1. Log in to your Mautic instance as an administrator.
2. Go to Settings (gear icon) > Configuration.
3. Click the API Settings tab.
4. Set API enabled? to Yes.
5. Click Save & Close.

Basic Auth Not Enabled in Mautic

Symptom: You are using Basic Authentication and the Test Connection returns a 401 Unauthorized error, even though your username and password are correct.

Solution: Mautic requires HTTP Basic Auth to be explicitly enabled in addition to the API itself.

1. In Mautic, go to Settings > Configuration > API Settings.
2. Set Enable HTTP basic auth? to Yes.
3. Click Save & Close.

Wrong Mautic URL

Symptom: The Test Connection fails with a “could not resolve host” error, or you get an unexpected HTML response instead of JSON.

Solution: Double-check the Mautic URL on the Connection tab. Common mistakes include:

• Including a trailing slash (for example, https://mautic.example.com/ instead of https://mautic.example.com)
• Using http:// when your Mautic instance requires https://
• Including the /api path (the plugin adds this automatically)
• A typo in the domain name

The URL should be the base address of your Mautic installation, such as https://mautic.example.com or https://example.com/mautic.

Wrong Credentials

Symptom: The Test Connection returns a 401 Unauthorized error.

Solution: Verify that the username and password (for Basic Auth) or the client ID and secret (for OAuth2) are correct. Try logging in to Mautic directly with the same credentials to confirm they work. If you recently changed your Mautic password, you will need to update it in the plugin settings as well.

Note that the password field on the Connection tab appears blank after saving. This is normal because the plugin stores it encrypted. Only enter a new value if you need to change the password.

OAuth2 Token Expired

Symptom: The connection was working previously but now returns a 401 error or “invalid grant” message.

Solution: OAuth2 tokens have an expiration time. The plugin automatically refreshes tokens when they expire, but this can fail in certain situations:

• The refresh token itself has expired (some Mautic configurations set a short refresh token lifetime)
• The OAuth2 client credentials were changed in Mautic
• The Mautic server was reinstalled or its database was restored from an older backup

To fix this, go to WooCommerce > Mautic Integration > Connection, re-enter your OAuth2 credentials, and click Authorize to complete the OAuth2 flow again.

SSL Certificate Errors

Symptom: The debug log shows an error like “SSL certificate problem: unable to get local issuer certificate” or “SSL certificate verify failed.”

Solution: This means your WordPress server does not trust the SSL certificate on your Mautic instance. This commonly happens when:

• Your Mautic instance uses a self-signed certificate
• The CA bundle on your WordPress server is outdated
• The Mautic SSL certificate has expired

To resolve this, check that your Mautic SSL certificate is valid and not expired. If it is a self-signed certificate, you may need to ask your hosting provider to add the certificate to the server’s trusted CA bundle. You can also test the certificate by visiting your Mautic URL in a browser and checking for certificate warnings.

Server Firewall Blocking Outgoing Requests

Symptom: The Test Connection hangs for a long time and then fails with a timeout or “connection refused” error.

Solution: Some hosting providers block outgoing HTTP requests from your WordPress server. The plugin needs to make outgoing HTTPS requests to your Mautic instance’s API endpoint.

Contact your hosting provider and ask them to confirm that outgoing HTTPS requests on port 443 are allowed from your server. Provide them with the domain name of your Mautic instance so they can whitelist it if necessary.

Mautic Behind HTTP Auth or Maintenance Mode

Symptom: The Test Connection returns a 401 or 503 error, even though your Mautic credentials are correct and the API is enabled.

Solution: If your Mautic instance is behind server-level HTTP authentication (such as .htpasswd protection), the plugin’s API requests will be blocked before they even reach Mautic. You will need to remove the HTTP authentication or configure an exception for the /api/ path.

Similarly, if Mautic is in maintenance mode, the API will not respond. Check your Mautic instance and make sure it is fully online and accessible.

General Debugging Tips

• Always enable Debug Mode on the Connection tab when investigating connection problems. The logs will show the exact HTTP status code and error message returned by Mautic.
• Try opening https://your-mautic-url.com/api/contacts?limit=1 in your browser while logged in to Mautic. If you see a JSON response, the API is working. If you see an error page, the problem is on the Mautic side.
• Check WooCommerce > Status > Logs for log files with the source mautic-integration-woocommerce.
• If you have made changes to your Mautic configuration, clear your Mautic cache by deleting the contents of the var/cache directory in your Mautic installation, or by running php bin/console cache:clear from the Mautic command line.