Troubleshooting & Recovery

This guide provides operational troubleshooting procedures and root-cause analyses for common failure scenarios encountered during WebHost Manager (WHM) integration with StackConsole CMP.

---

1. Quick Diagnostic Matrix

Symptom	Likely Cause	Verification	Resolution	Expected Outcome
Web Hosting missing from sidebar	Module disabled or role permission missing	Check tenant modules and user role permissions	Enable Hosting module; run permission seeders; assign Web Hosting Manage or Web Hosting Read.	Web Hosting appears under the navigation menu.
No plans on purchase page	Inactive plan, wrong rate card, or region not linked	Inspect rate card assigned to client and zone mapping	Ensure plan is Active, mapped to the correct region, and present in the client's rate card.	Plans display with price cards on /app/web-hosting/create.
"Check Connection" fails with 403 Forbidden	Invalid API token or insufficient ACL permissions	Test token manually via curl with listpkgs	Revoke token and regenerate a new WHM API token with required privileges (list-pkgs, create-acct, etc.).	Connection test passes with a green success message.
"Check Connection" fails with SSL Error	Untrusted or mismatched SSL certificate	Inspect SSL certificate on port 2087	Install a valid CA-signed certificate for the WHM hostname, or temporarily disable SSL verification in dev.	HTTPS handshake completes without certificate errors.
WHM Package missing from CMP dropdown	Package uses uppercase letters, or uses an underscore without a root_ or reseller prefix	Check the name in WHM Packages → Edit a Package.	Follow the package naming rules in WHM Package Naming. Use a space (such as basic hosting), or prefix an underscore with root_.	The package appears in the CMP dropdown after you click refresh.
Account stuck in creating state	Queue worker stopped or crashed	Run supervisorctl status on CMP server	Start the virtual-machine queue worker and check laravel.log for worker crashes.	Worker picks up CreateHostingAccountJob and transitions state to active.
Account in failed state after invoice generated	WHM provisioning error (username collision, disk full)	Check CMP activity logs and WHM /var/cpanel/accounting.log	Resolve WHM-side conflict, verify package limits, and reconcile using the manual recovery workflow.	Account provisioned successfully and marked active.
cPanel SSO returns 502 / Auth error	Missing create-user-session ACL or account suspended	Verify account state in CMP and API token permissions	Ensure account is Active and the WHM token has the SSO session privilege.	SSO URL generates and redirects directly into cPanel.
Plan Upgrade blocked / returns 403	Attempting to downgrade or select equal quota	Check disk_quota_gb on current vs destination plan	Customers can only upgrade to plans with strictly higher disk_quota_gb.	Upgrade form enables the "Review & Upgrade" button.
Web Hosting spend shows $0 in reports	Cost report filtered by another orchestrator	Check selected Cloud Provider filter in billing summary	Change the billing provider filter to the WHM Cloud Provider setup.	Web hosting invoice amounts display accurately.

---

2. API & Network Diagnostic Commands

Execute these commands from the CMP application node terminal to isolate network and authentication issues:

1. Test Inbound TCP Port 2087

nc -zv -w 5 <whm-server-ip-or-hostname> 2087

• Success Output: Connection to <host> 2087 port [tcp] succeeded!
• Failure Output: Connection timed out or Connection refused. Verify that port 2087 is open in WHM's firewall (CSF) and that the CMP IP is allowlisted.

2. Verify WHM SSL Certificate

echo | openssl s_client -connect <whm-server-hostname>:2087 -servername <whm-server-hostname> 2>/dev/null | openssl x509 -noout -issuer -subject -dates

• Verify that the issuer is a recognized public Certificate Authority (e.g., Let's Encrypt, Sectigo) and that the certificate has not expired.

3. Test API Token & Package Retrieval

curl -H "Authorization: whm <username>:<api_token>" \
     https://<whm-server-hostname>:2087/json-api/listpkgs?api.version=1

• Success Output:

  {"metadata":{"command":"listpkgs","reason":"OK","result":1,"version":1},"package":[{"name":"basic_plan",...}]}

• Failure Output: HTTP 403 Access Denied. Verify that the token is active and has the list-pkgs privilege enabled.

---

3. Provisioning Reconciliation Workflow

Operational Reality

CMP does not feature an automated "Retry" button on failed accounts. This prevents race conditions where duplicate cPanel accounts or double billing invoices might be created.

When an account enters the failed state after an invoice has already been issued, follow this reconciliation procedure:

Step 1: Identify Failure Cause

1. In the CMP Admin Portal, navigate to Clients → [Target Client] → Web Hosting → [Select Account].
2. Open the Activity Logs tab and inspect the error message on the HOSTING.ACCOUNT.CREATE event.
3. Common error responses:
   • "A DNS entry for the domain already exists."
   • "The username 'xxx' is already in use on this system."
   • "Package 'xxx' does not exist."

Step 2: Resolve WHM Condition

• If DNS or username exists from a previous orphaned attempt, remove the obsolete zone in WHM under DNS Functions → Delete a DNS Zone.
• If the package name was incorrect, update the CMP plan mapping or recreate the package in WHM using lowercase letters.

Step 3: Reconcile Account

• If the cPanel account was actually created on WHM before the worker timed out, CMP's idempotency check allows you to transition the account state safely:

  php artisan tinker --execute="Modules\Hosting\Entities\HostingAccount::where('id', '<account_id>')->update(['state' => 'active']);"

• If the account was not created, re-queue the provisioning job:

  php artisan tinker --execute="dispatch(new Modules\Hosting\Jobs\CreateHostingAccountJob(Modules\Hosting\Entities\HostingAccount::find('<account_id>')));"

---

4. Database Seeders & Permission Fixes

If administrators or customers cannot see Web Hosting menus after deployment, re-run the required database seeders:

# Seed hosting account template definitions
php artisan db:seed --class='Modules\Hosting\Database\Seeders\HostingAccountTemplateSeeder'

# Seed Web Hosting permissions into Master Seeder
php artisan db:seed --class='Database\Seeders\MasterSeeder\Permissions\WebHostingPermissionSeeder'

Master Permissions Reference

Permission Key	Minimum Role	Capabilities
hosting.accounts.index	Customer / Admin	View the list of web hosting accounts
hosting.accounts.show	Customer / Admin	View account overview, disk usage, and DNS tabs
hosting.accounts.create	Customer	Order and provision new hosting services
hosting.accounts.sso	Customer / Admin	Generate one-click cPanel SSO login sessions
hosting.accounts.credentials	Customer / Admin	Reset cPanel master account password
hosting.accounts.upgrade-plan	Customer	Submit in-place package upgrades
hosting.accounts.delete	Customer / Admin	Request immediate or end-of-period cancellation
billing.summary.index	Customer	Access billing proration preview during upgrades

---

Related Documentation

• WHM Requirements Checklist
• Connecting CMP to WHM
• Package & Plan Configuration
• WHM Package Naming Guide
• Billing, Lifecycle & Subscriptions