Panelbotdocs
SearchStart free

Troubleshooting your setup

Fixes for common Panelbot setup snags: a refused server credential, an agent that will not connect, a failing billing test, or a missing widget.

When setup does not go cleanly

Most Panelbot setups connect on the first try, but a few common snags account for nearly all the ones that do not. Each has a plain cause and a plain fix. Work through the one that matches your symptom, and if it is not resolved by the end, the last section covers how to reach us with the right information.

A server does not appear after installing the connector

The connector runs inside your billing portal, so it only runs when your portal runs it.

  • The portal’s cron is not running. On WHMCS the hook sends a server when you add or save it, and after each system cron run it re-checks your servers for changes and delivers any approved agent installs, so servers that existed before you installed the hook, and agent installs, depend on that cron. Confirm it is running, or open and save the server to send it right away. On Blesta the plugin adds a cron task, PanelBot Connect server sync, that runs every 5 minutes on Blesta’s own cron.
  • “SSL certificate problem” in the log. A new cPanel or DirectAdmin server often serves its panel with a self-signed certificate, and the connector always verifies certificates. Either install a trusted certificate on the panel, or point the connector at a CA bundle file that holds your system CA bundle plus that panel certificate: set PANELBOT_CA_BUNDLE in the server connector section of panelbot_hook.php, or on Blesta fill in CA bundle path (optional) on the plugin’s manage page. Verification is never turned off. The hook logs these lines to the portal’s activity log; the Blesta plugin writes them to the PHP error log.
  • You downloaded the file again. Each download of the WHMCS file or Blesta plugin, from the Widget page or the connect page, makes a new connect key. The file you already installed keeps working until you upload the new one; once the new file connects, the key inside the older copy stops working. Install the newest download and remove any older copy, including the older separate connector (panelbot_connect_hook.php and the panelbot_connect/ folder on WHMCS, the PanelBot Connect plugin on Blesta) if you still have it.
  • The server is not a cPanel/WHM or DirectAdmin server in your portal. The connector only sends servers of those two types. The hook also skips a server with no hostname or username, and logs that it did.
  • The server shows Could not connect. The billing file reports every server entry, including the ones it could not connect. Open the Billing server scan (Billing, then Scan servers): the entry shows Could not connect: and the reason. If an entry says Not reported yet - install the billing file, the file has not reported it yet: install your newest download and wait for the next billing cron run.

The server credential is refused

You connected a server over the panel API, but Panelbot reports that the credential does not work.

  • The credential is for the wrong server or user. A WHM API token or DirectAdmin login key belongs to one user on one server. Confirm the hostname matches and that the token or key was created for the user you meant Panelbot to act as.
  • The credential was rotated or revoked on the panel. Panelbot cannot use a credential the panel no longer accepts. Generate a fresh one and reconnect the server.
  • The capability list is shorter than expected. That is not a fault. A reseller credential, or a root token with narrow permissions, reaches less, and Panelbot shows you exactly what it reaches. A reseller login missing some WHM privileges still connects, and the server’s details show Narrower than expected with what is missing. Widen the credential on the panel side and reconnect if you need more, or leave it as it is.
  • A server will not save as a VPS or dedicated server. A reseller login has no root access. Connect the server with a WHM root token or a DirectAdmin admin login key, or keep it as a shared hosting or reseller server.

Full steps are in Connect your first server.

The optional agent will not connect

You chose to install the optional agent, but the server still shows no agent connection on your Servers page. The server keeps working over its panel credential in the meantime.

  • Outbound HTTPS is blocked. The agent reaches out to Panelbot over an outbound HTTPS connection; it never accepts inbound connections. If the server’s own firewall or an upstream network blocks the agent’s outbound HTTPS traffic, enrollment cannot complete. Confirm the server can make outbound HTTPS connections and try again.
  • The message bus port is blocked. The agent also connects out to Panelbot’s TLS message bus (port 6379 by default). If that is blocked, the agent still enrolls and reports over HTTPS, but the Servers page keeps a warning until the port is open; the installer prints the exact host and port. On CSF the installer adds this rule itself, so a block there usually comes from a provider or upstream firewall.
  • The enrollment token expired. Tokens are deliberately short-lived and single-use, so one generated a while ago, or already used once, will not work. Generate a fresh token right before installing and run the command promptly.
  • The installer reported an error. The installer prints a diagnostic when something goes wrong rather than leaving the server half-configured. Re-check the SSH output, address what it names, and run the command again. Full steps are in Install the server agent.

The billing connection test fails

You entered your billing portal details, but the connection test does not pass.

  • The API address or key is off. A small typo in the portal URL or a mistyped or revoked API key is the usual cause. Re-copy both from your billing portal and test again.
  • The API user lacks permission. Panelbot needs to read your service list to know who owns what. If the API credentials do not have permission to list services, the test can fail or come back empty. Grant the API user permission to read accounts and services, then retest.
  • The portal is not reachable. If your billing portal restricts which addresses may call its API, it may be turning Panelbot away. Allow Panelbot to reach your portal’s API and test once more. The full flow is in Connect your billing portal.

The widget does not appear on your portal

The chat launcher is not showing up where you embedded it.

  • The widget is disabled. The widget has an on/off switch in its settings, and it will not render while it is off. Confirm it is enabled in Configure and enable the chat widget.
  • The embed snippet is missing or misplaced. The launcher only appears where the snippet is present. Make sure the snippet is pasted into a template that actually loads on the pages you are checking, not a page you are not viewing. See Embed the widget on your portal.
  • You are looking at a logged-out page. The widget is meant to run where your customer is signed in, so your portal can vouch for who they are. On a page with no signed-in customer, it may not show or may show without a recognised identity.

A customer is not recognized in chat

The widget loads, but Panelbot does not seem to know who the customer is or what they own.

  • The customer is not signed in to your portal. Identity comes from your billing portal, which vouches for the customer with a secure token when they are signed in. If they are not signed in, there is no identity to trust for that session.
  • The service list has not synced. Panelbot checks ownership against the services synced from your billing portal. If a customer or a recently added service is missing, re-run the connection and scan so the latest services are pulled in. See Connect your billing portal.
  • The account maps to a server you have not connected. If the customer’s account lives on a server Panelbot does not yet know about, connect that server so their account is in scope. See Connect your first server.

Chat is not escalating to your team

Panelbot is not handing conversations off when you expected it to.

  • No escalation contact is set. Handoffs go to the contact you nominate for your account. If none is set, there is nowhere for an escalation to land. Set your escalation contact in your account settings.
  • You expected escalation for something it resolved on its own. Read-only diagnostics and any reversible fixes you have enabled are handled without a handoff by design. Panelbot escalates when it is not confident, when a change is risky, or when the issue is out of scope, so a smoothly resolved routine case will not produce a handoff. See When a human takes over.

When to contact support

If you have worked through the relevant section and setup is still not connecting, reach out to us. It helps to tell us which step you are on, the exact symptom you see, and, for agent issues, the diagnostic message the installer printed over SSH. Please do not send secrets such as API keys or tokens; we do not need them to help, and they should stay in your own systems. With the symptom and the step, we can point you to the cause quickly.

Where to go next