Troubleshooting

Where to look when provisioning stalls, DNS or TLS is pending, or an auth flow misbehaves. Start with Diagnostics → Health Checks — most symptoms map to one failing check.

Start at: Diagnostics → Health Checks

1. Run the health checks first

Almost every operator symptom maps to one failing check under Diagnostics → Health Checks. Run them before digging deeper:

Check	Verifies
Cron Jobs	Core registration and last-run freshness for all Auth automation.
VPS Providers	Each configured provider API responds (no SSH needed).
DNS Provider	The Cloudflare token can read the zone and write a test TXT record.
Auth Control Planes	Each Admin Proxy /health answers; updates last health.
Email Delivery	Managed SMTP config and public sender-domain DNS.
Cloudflare for SaaS	Custom hostname, DNS, certificate, and fallback-origin access.
WHMCS Product Sync	Synced plans still point at WHMCS products that exist.
Cloud-Init Template	The control-plane bootstrap template is present and has its required inputs.
Schema & Runtime	Expected tables, module version, PHP, and the ionCube loader.
Provisioning Preflight	A no-resource preflight of the provisioning pipeline.

2. Provisioning & orders

Order stuck pending

The project is created when WHMCS runs the module’s Create command (at order acceptance or payment, per the product’s auto-setup setting): the JWT secret, database schema/role, anon + service-role keys, env, route, and auth-engine service. If the control plane didn’t answer, the project stays provisioning or provision_failed and the provision cron (every 2 minutes) retries it — check that cron in ImpulseCore’s Cron tab and the target server’s Admin Proxy health. If a requested region has no capacity the order fails loudly; add a control plane in that region.

Provider test fails

Re-check the provider token, default region/plan, and provider-side account limits. Re-run Health Checks → VPS Providers — it exercises the provider API directly, no SSH involved.

Control plane stays provisioning

Inspect the provider create status, the cloud-init/bootstrap log (View Log on the server row), and Admin Proxy health. The row flips to active once the Admin Proxy answers /health; a row still provisioning after the provisioning timeout (default 30 minutes, under Settings → General & Access) is marked provision_failed, and recovers by itself if the host answers later.

Proxmox provision has no IP

Confirm the template has qemu-guest-agent installed and enabled and that guest networking works. Without the agent, WHMCS cannot learn the instance IP.

3. Server unreachable & apply issues

Server shows unreachable

Run Health Checks → Auth Control Planes. Confirm the firewall still allows 9098 and 9099 from your WHMCS host over both IPv4 and IPv6, and that the server’s Admin Proxy secret matches. A one-family IP mismatch is the most common cause of a host that is up but reads unreachable. A TLS pin mismatch means the proxy’s certificate changed: if you know why (for example, the box was rebuilt), use Re-pin TLS from the server’s menu; if you don’t, treat it as a possible interception and investigate first.

Apply falls back / bundle mismatch

A self-updating apply waits for the restarted Admin Proxy bundle hash and runs a second pass rather than dropping to SSH. If the result says reapply required, wait about 30 seconds and run Apply/Rebuild again. If Preview Apply reports a deferred env key, re-run apply once the bundle has restarted so the new key is validated against the running bundle.

Blank engine version column

The effective auth-engine version is read from the security snapshot. If the column is empty, run a security status refresh from Operations.

Deeper diagnosis

Tail the bootstrap log from the server row and review the admin-action log blocks captured for each proxy operation. Module and admin actions are also recorded in ImpulseCore’s audit log.

4. DNS, TLS & custom domains

Wildcard TLS not issuing

DNS-01 wildcard issuance needs a Cloudflare token with zone-read and DNS-edit scope. A failing DNS Provider check almost always means the token is missing DNS-edit permission. If the bootstrap log shows No TXT record found, raise the DNS-01 propagation delay under Settings → DNS & TLS (60–120 seconds). If a certificate needs replacing, use Reissue TLS from the server’s menu (POST /admin/v1/tls/reissue) rather than a rebuild.

Custom domain stuck pending

Almost always a missing or incorrect CNAME. Confirm the customer’s CNAME matches the exact target shown in their Domains tab and that your Cloudflare-for-SaaS fallback origin is reachable. The domain_polling cron refreshes custom-domain DNS/TLS state every 15 minutes.

Proxied custom hostnames

If a customer orange-clouds their Auth API hostname, the paths /auth/v1/* and /oauth/v1/* must bypass cache, bot/WAF challenges, redirect/transform rules, and query-string normalization — otherwise one-time login state is stripped and OAuth callbacks break.

5. Authentication flows

Email not delivering

Re-check Settings → Email Delivery and the Email Delivery health check, and confirm the SPF/DKIM records for the sender domain are published. The SMTP settings for Auth transactional email (confirmation, recovery, invite, magic link) come from ImpulseCore’s Email Delivery and are baked into each control plane when it is provisioned or reapplied — after changing them, run Apply/Rebuild on each control plane.

Google/Microsoft returns bad_oauth_state

The provider reached the endpoint, but the one-time login state was missing, expired, cached, or consumed before the callback completed. Confirm the provider callback is the project’s current Auth API callback, then apply the bypass rules above for /auth/v1/* and /oauth/v1/* on any proxied custom hostname. Note that external providers use the primary Auth API domain as their callback host, so a default-endpoint callback stops matching once a custom domain is primary.

Project order does not create an endpoint

Confirm the WHMCS product is synced to an active Auth plan and that at least one control plane is active in the selected region.

6. Lifecycle & license

Terminated project not purging (or purging twice)

Termination fences access, marks the tenant pending_purge, and stamps purge_after = now + 7 days. Hard purge is idempotent and cron-driven — an already-dropped project will not double-decrement capacity. Use the Restore (cancel purge) action during the grace window; after it, deletion is permanent.

License shows No License / Invalid

Use Re-check now on the ImpulseAuth row under ImpulseCore → Modules & Licensing → Licenses and confirm the status under Diagnostics → License. Gated tabs mean the license is not active or Core cannot reach the licensing endpoint. Core remains the source of truth for license state, grace windows, and revalidation. If you moved WHMCS, update its domain under Change domain on the license in the Impulse Software portal (for a new server IP, contact support), then click Re-check now under ImpulseCore → Modules & Licensing → Licenses.

Addon activates but tabs stay gated

Verify the IAUTH- key in Core and confirm Core can reach the licensing endpoint. If ImpulseAuth is missing from Core’s Modules list, deactivate and reactivate the addon while Core is active so Core re-reads the manifest.

Stuck on something not listed?

Open a ticket at support.impulsesoftware.com or email [email protected], and include the ImpulseAuth version, what you were doing and what you saw. The Diagnostics tab’s health checks show what’s failing.

Help Center Back to docs