Skip to main content

Troubleshooting

This guide helps WHMCS administrators diagnose common Extendy GeoShield issues using existing settings, the Login Events Log, provider test results, and safe WHMCS Activity Log summaries.

It does not include destructive database repair steps, manual table deletion, or addon code changes.

Start with these checks​

Before investigating a specific symptom, confirm:

  1. Extendy GeoShield is activated in WHMCS.
  2. Addon Enabled is set to Yes in the Extendy GeoShield Settings page.
  3. The relevant login happened after the addon was enabled.
  4. The Login Events Log contains a row for the login.
  5. The event’s Decision, Alert Sent, Alert Error, IP Address, Country, Provider, IP Source Used, and IP Source Verified fields match your expectation.

For configuration reference, see Configuration Guide.

For event fields, see Login Events Log.

No login event appears​

Likely verified causes:

  • Addon Enabled is set to No.
  • The login happened before Extendy GeoShield was enabled.
  • The action was not a normal client-area login event processed by the addon.
  • The addon could not safely record the event and wrote only a safe WHMCS Activity Log summary.

Checks:

  • Confirm Addon Enabled is Yes.
  • Confirm you are reviewing the correct time range in the Login Events Log.
  • Check whether retention cleanup may have removed older event rows.
  • Check WHMCS Activity Log for a safe summary such as the addon being unable to record a client login event.

Corrective action:

  • Enable the addon and test with a controlled client-area login.
  • If older rows are missing, review Retention.

A login event exists but no alert email was sent​

A recorded login event does not mean an email must be sent.

Likely verified causes:

  • The event decision was suppressed by trusted-country logic.
  • Smart Mode found the country already known for the current context.
  • The event was suppressed by alert cooldown.
  • Country detection failed and Alert When Country Detection Fails is set to No.
  • No safe Client Account context was available for the event.
  • The primary Client Profile email was missing or invalid.
  • The selected Extendy GeoShield email template has copied recipients configured.
  • WHMCS SendEmail failed or was aborted before delivery.

Checks:

  • Review Decision, Decision Reason, Alert Sent, Alert Template, and Alert Error in the Login Events Log.
  • Confirm the event has decision_result = alert_required when an email is expected.
  • Confirm the event has a safe client_id context.
  • Confirm the primary WHMCS Client Profile email is present and valid.
  • Confirm the relevant Extendy GeoShield email template has no copied recipients configured.
  • Confirm WHMCS mail delivery is working in your WHMCS environment.

Corrective action:

  • Adjust trusted countries, alert mode, cooldown, or detection-failure settings as appropriate.
  • Resolve missing client context or Client Profile email issues.
  • Remove copied recipients from Extendy GeoShield alert templates.
  • Use WHMCS mail troubleshooting for final delivery issues.

Related documentation:

Alert email was suppressed​

Suppressed events are still useful. They show that the addon evaluated a login and decided no email was required.

Common suppressed decision categories include:

  • trusted country;
  • known Smart Mode country;
  • country detection failure when detection-failure alerts are disabled;
  • cooldown.

Checks:

  • Review Decision and Decision Reason in the Login Events Log.
  • Review Alert Mode and Alert Cooldown settings.
  • Review Trusted Countries and Smart Mode.

Corrective action:

  • If suppression is expected, no action is required.
  • If suppression is not expected, review the country trust model and cooldown configuration.

Email recipient is not the WHMCS User email​

This is expected in the current MVP recipient model.

Extendy GeoShield sends alert emails to the primary WHMCS Client Profile email for the safely resolved Client Account context.

The WHMCS User email remains the login actor and is included in email content as user_email.

If no safe Client Account context is available, no email is sent in the current MVP.

Related documentation:

Email templates appear missing​

Extendy GeoShield uses these WHMCS General email templates:

Extendy GeoShield - Login Alert
Extendy GeoShield - Smart New Country Alert

The addon ensures these templates during activation and when the admin addon page is loaded.

The template ensure logic creates missing master/default language rows and does not intentionally duplicate existing templates or overwrite existing template content.

Checks:

  • Open the Extendy GeoShield addon page in WHMCS Admin.
  • Check WHMCS email templates for the exact template names above.
  • Confirm the template type is compatible with WHMCS General email sending.

Corrective action:

  • If a template is missing, open the addon admin page or reactivate the addon through WHMCS Admin to trigger safe template ensure logic.
  • Do not create duplicate templates with slightly different names.

Country is Unknown or GeoIP lookup fails​

Likely verified causes:

  • No GeoIP provider is selected.
  • Provider credentials are missing, invalid, or cleared.
  • The resolved client IP is empty or not a valid public IP.
  • The provider request failed, timed out, was rejected, or returned no usable country data.
  • The selected provider setting was changed in the form but not saved before testing.

Checks:

  • Confirm GeoIP Provider is set to IPinfo or MaxMind.
  • Confirm the relevant provider credentials are saved.
  • Use GeoIP Provider Test Connection with a real public test IP.
  • Review IP Address, Provider, Country, and Country Code in the Login Events Log.
  • Review Alert When Country Detection Fails.

Corrective action:

  • Save the intended provider setting before using Test Connection.
  • Re-enter or clear/re-enter credentials as needed.
  • Fix IP source configuration if no public client IP is available.
  • If country detection failure alerts are desired, set Alert When Country Detection Fails to Yes.

Related documentation:

IPinfo connection test fails​

Checks:

  • Confirm GeoIP Provider is saved as IPinfo.
  • Confirm an IPinfo API token is stored.
  • Confirm the test IP is a valid public IP address.
  • Remember that the token is sent using the HTTP Authorization: Bearer header, not in the URL.

Corrective action:

  • Save the IPinfo provider setting.
  • Re-enter the token if needed.
  • Test again with a public IP address.

Extendy GeoShield does not document or control IPinfo account limits, billing, retention, or provider-side logging.

MaxMind connection test fails​

Checks:

  • Confirm GeoIP Provider is saved as MaxMind.
  • Confirm both MaxMind Account ID and MaxMind License Key are stored.
  • Confirm the test IP is a valid public IP address.
  • Remember that the current implementation uses the MaxMind GeoIP2 Country web service, not a local MMDB database.

Corrective action:

  • Save the MaxMind provider setting.
  • Re-enter the Account ID or License Key if needed.
  • Test again with a public IP address.

Extendy GeoShield does not currently support local MaxMind database file troubleshooting.

The wrong client IP is detected​

Likely verified causes:

  • The selected Client IP Source does not match your network topology.
  • REMOTE_ADDR mode is being used behind a proxy, so WHMCS sees the proxy address.
  • X-Forwarded-For is ignored because the immediate peer is not a configured trusted proxy.
  • CF-Connecting-IP is ignored because the immediate peer is not recognised as Cloudflare.
  • The environment uses private or local network addresses and no valid public client IP is available.

Checks:

  • Review IP Source Used and IP Source Verified in the Login Events Log.
  • Confirm Client IP Source in Settings.
  • For proxy setups, review Trusted Proxy IPs / CIDRs.

Corrective action:

  • Use REMOTE_ADDR unless a verified proxy or Cloudflare setup requires a header.
  • Use X-Forwarded-For only with deliberate trusted proxy ranges.
  • Use CF-Connecting-IP only when WHMCS is actually behind Cloudflare.

Related documentation:

X-Forwarded-For is ignored​

Verified behaviour:

  • X-Forwarded-For is considered only when REMOTE_ADDR matches a configured trusted proxy range.
  • The chain is evaluated from right to left.
  • Trusted proxy hops are removed from the right side.
  • The first valid public non-proxy IP is selected.
  • Missing, malformed, overly long, proxy-only, private, reserved, or otherwise unusable chains fall back safely.

Checks:

  • Confirm Client IP Source is X-Forwarded-For.
  • Confirm Trusted Proxy IPs / CIDRs contains the immediate proxy address or range.
  • Confirm the header chain contains a valid public client IP.

Do not fix this by trusting arbitrary broad CIDR ranges.

CF-Connecting-IP is ignored​

Verified behaviour:

  • CF-Connecting-IP is accepted only when REMOTE_ADDR belongs to the bundled Cloudflare CIDR ranges.
  • Header presence alone is not enough.
  • If the request does not arrive through a verified Cloudflare range, Extendy GeoShield falls back safely.

Checks:

  • Confirm Client IP Source is CF-Connecting-IP.
  • Confirm the WHMCS hostname is actually proxied through Cloudflare.
  • Confirm direct access to the origin is restricted where possible.

The Cloudflare range list is bundled as a reviewed snapshot and is not automatically updated during login.

IP address is empty​

This can happen when no valid public client IP is available.

Common cases include:

  • local development;
  • private networks;
  • container or internal proxy topologies;
  • fallback to REMOTE_ADDR where REMOTE_ADDR is private/local/reserved.

The login event can still be recorded. GeoIP country detection may fail.

This is expected.

Trust links require WHMCS authentication. Opening a trust link while logged out must not trust a country.

After login, the trust action must be revalidated against the token, WHMCS User, and Client Account context.

Verified causes include:

  • the token is missing or invalid;
  • the token has expired;
  • the token was already used;
  • the logged-in WHMCS User does not match the token;
  • the selected Client Account context does not match the token;
  • an admin masquerading session attempted the trust action.

Trust links expire after 48 hours and can be used only once.

Corrective action:

  • Use the latest security alert email.
  • Log in as the same WHMCS User that received the alert.
  • Select the matching Client Account context when the token is client-bound.

Do not expect receiving or opening the email by itself to trust a country.

Smart Mode did not automatically trust a country​

This is expected.

Smart Mode records and evaluates known countries, but a new country is not automatically trusted merely because a login occurred.

For eligible Smart New Country alerts, the email may include a trust link. The trust action requires WHMCS login and strict token/user/client validation.

A no-client-context country does not automatically become trusted for all linked Client Accounts.

Related documentation:

Old events are not being cleaned up​

Likely verified causes:

  • Retention is set to Disabled (Automatic Cleanup Off).
  • WHMCS cron is not running.
  • The row is not older than the calculated 180-day cutoff.
  • The cleanup has not yet run after the row became eligible.

Checks:

  • Confirm Retention is set to 180 Days.
  • Confirm WHMCS cron is running normally.
  • Check WHMCS Activity Log for safe retention cleanup summaries.

Retention cleanup removes only old rows from mod_extendy_geoshield_events. It does not clean known countries, trust tokens, settings, email templates, WHMCS Activity Log entries, or backups.

Retention Disabled did not delete existing events​

This is expected.

Disabled (Automatic Cleanup Off) means automatic cleanup is disabled. It does not delete existing login event rows and does not prevent new rows from accumulating.

For details, see Retention.

Provider credentials appear masked​

This is expected.

Provider credentials are stored using the verified WHMCS EncryptPassword / DecryptPassword Local API mechanism and are displayed as masked values in the admin UI.

Leaving a credential field empty during save keeps the existing stored value. Use the explicit clear/remove action to remove a stored credential.

Do not try to recover or display stored provider secrets from the admin UI.

Deactivation did not remove stored data​

This is expected.

Deactivation preserves addon data. It is not a full removal operation.

Extendy GeoShield does not add table-drop logic to deactivation and does not rely on a separate documented WHMCS addon uninstall callback.

The full Manual Full Removal / Uninstall Procedure is a separate documentation topic.