CaveCMS
Troubleshooting · cPanel

cPanel snags,
and how to clear them.

Shared cPanel / LiteSpeed hosting runs your app on a private socket behind a process manager, with the whole account boxed into a memory and connection budget. That setup causes a handful of recognisable snags. Here is each one: what you see, why it happens, and the exact fix. Most are already handled in a recent version, so the first move is usually to update.

On this page

Terminal / SSHFirst, updateHow to restartUnstyled siteWizard 404Connection limit503 errorsLogin URL 404Update failsSite URLOut of memoryRestore stuckWrong accountOld site still showsWhen to call your host

Symptom

Terminal won’t open, or it says shell access is disabled.

SSH is off by default on most shared plans, and the switch lives in a different place per host. Namecheap: cPanel → Manage Shell (their own plugin) → turn SSH on, then Advanced → Terminal works. GoDaddy: the GoDaddy dashboard → Manage → Settings → SSH access. Bluehost and HostGator: cPanel → Security → SSH/Shell Access → Real Shell. A2: already on. If you enabled SSH but there is still no Terminal icon, your host hid the in-browser one, so SSH in from your own computer (ssh user@your-host -p PORT) and run the same commands there.

Nothing works?

One message to your host clears it: “Please enable SSH / shell access for my account.”

Start here

Almost everything is fixed by updating.

The cPanel-specific issues below were resolved across 0.2.2 to 0.2.6. If your install is behind, the cleanest fix for most of this page is a fresh install of the latest release over your existing database, which keeps your content and applies all the fixes at once.

Check your version at the bottom of the admin sidebar (under the CaveCMS mark). The deploy runbook covers the content-preserving reinstall.

The deploy runbook →

In cPanel — Terminal (your app's folder)

# the installer that ships every fix
npx create-cavecms@latest --surface=cpanel

# point at your EXISTING database when asked — your content is preserved

The one move you'll repeat

How to restart the app.

Many fixes end in “restart the app”. On cPanel that means restarting the Node application, not your whole account. Two ways:

cPanel UI

Setup Node.js App → open your app → Restart. This is the canonical way.

Stop, then start

If a restart doesn’t take, use Stop App, wait a minute, then Start App. This also frees any stuck processes from a previous run.

Symptom

The site loads as plain HTML.

No fonts, no colours, no layout, just unstyled text. The CSS and JavaScript aren’t loading.

Why: the bundled server looks for static assets in a specific folder; on a fresh install they hadn’t been placed there yet. Fixed in 0.2.2+

Fix

Update to the latest version (see above), then restart the app. The startup file now stages the assets automatically on every boot. If you just updated, a hard refresh in your browser clears any cached unstyled page.

Symptom

The setup wizard shows 404.

Opening /install on a brand-new install returns “not found”, so you can’t create your admin account.

Why: the app runs on a private socket, so its security layer couldn’t reach its own settings and assumed the site was already set up. Fixed in 0.2.2+

Fix

Update to the latest version. Then open the install link the installer printed at the end. It includes a one-time token (/install?t=…). Open the plain /install without that token and the wizard can’t create the account.

Symptom

Install fails: “max_user_connections”.

The install (or an update) stops at the database step with a max_user_connections error, and re-running doesn’t help.

Why: shared hosts cap how many database connections your account can hold at once, and the host can keep a previous copy of the app running that uses them all up. Fixed in 0.2.3+. The installer now waits its turn and keeps a small connection pool.

If you’re on an older version and hit it now

  1. cPanel → Setup Node.js App → your app → Stop App. Wait a minute.
  2. cPanel → phpMyAdmin, open your database, and on the SQL tab run SHOW PROCESSLIST;. If rows for your database user linger, end each with KILL <Id>;.
  3. Start the app again (or re-run the install), then continue.

Symptom

503 Service Unavailable.

The site (or just the admin) shows “503 Service Unavailable”, sometimes with nothing in the app log.

Why: the web server couldn’t get a response from the app. Three common causes on cPanel: the app is stopped, it ran out of memory (see below), or the account has stuck processes from earlier crashes.

Fix, in order

  1. Confirm the app is started in Setup Node.js App, then restart it.
  2. Check memory (see Out of memory).
  3. If it stays down with a healthy database and enough memory, the account likely has stuck processes. Ask your host to reset (restart) your virtual environment. This clears any wedged processes for your account. It’s a routine, safe request and often the final fix after a rough day of crashes.

Symptom

Your custom login URL 404s.

You changed your login address (in the wizard or Settings → Security) and now both the new and the old URL return 404. You’re locked out.

Why: on a private socket the routing layer read the old login address and the new one never reached it. Fixed in 0.2.4+. The login address now stays in sync automatically.

Fix

Update to the latest version, then change the login address again from Settings → Security. It now applies on the spot, no server file editing.

Symptom

Updates fail early.

The in-dashboard update stops at “Getting ready” or “Preparing your data” and rolls back, leaving you on the old version.

Why: the update’s health check probed a local address the private-socket app can’t answer, and older installs were missing a path the data step needs. Fixed in 0.2.4+

Fix

Because the broken updater is the one trying to update itself, do this one update by reinstalling the latest version over your existing database (deploy runbook). From then on, in-dashboard updates work normally on cPanel. The failed-update window also has a “Show technical details” link with the logs if you want to see exactly which step stopped.

Symptom

Updates fail, and your sitemap and emails point at localhost.

Updates won’t finish, your sitemap and robots.txt come back empty, and the links in your emails point at localhost instead of your domain.

Why: your Site URL is set to a local address like https://localhost:3040. Setup pre-fills this from the address you opened it with, so reaching the wizard over an SSH tunnel or a localhost forward can save localhost by mistake. The updater, sitemap, and emails all read this one setting. Fixed in 0.2.8+. Setup now refuses a localhost Site URL on a live install, and the updater names the address it tried instead of failing quietly.

Fix

Open Settings → General and set Site URL to the real public address visitors use, for example https://yoursite.com (https, no trailing slash). On a recent version, Settings → Updates shows a notice with a one-click link whenever your Site URL is localhost, so you catch it before an update fails.

Symptom

Mystery 503s under load, or out of memory.

The site goes down with no clear error, especially right after a new version is available, or while doing heavier work, then recovers, then drops again.

Why: shared hosting caps your whole account’s memory, and the app didn’t know its ceiling. Fixed in 0.2.5+. Fresh installs now size themselves to your plan’s memory and pull updates in a memory-polite way.

Fix

The memory tuning is applied at install time, so a fresh install of the latest version is what enables it. Settings → Updates now shows your plan’s memory and flags it when it’s tight. If it’s tight, the real fix is a bigger plan. Ask your host to raise your account to 2 GB of memory, which gives a CaveCMS site comfortable headroom.

Still getting repeated 503s (or a 508 “Resource Limit Reached”) even on a roomier plan? On CloudLinux hosts your account has hard per-account caps (called LVE) on memory and on concurrent processes, and the app runs inside a virtualized filesystem (CageFS). Ask your host to raise your account’s physical memory and entry-process (EP) limits, and if files ever seem to go missing or stale, to rebuild your CageFS. One message does it: “Please raise my LVE memory and entry-process limits, and rebuild my CageFS.”

Symptom

A restore sticks on “Verifying”, or reverts.

A restore puts your content and media back, reaches “Verifying”, then either spins forever or undoes itself and shows the old site.

Why: the final health check used the same local address the private-socket app can’t answer, so it timed out and rolled back a restore that had actually succeeded. Fixed in 0.2.6+. Restores now verify over your real address.

Fix

Update to the latest version and restore again. Note: an encrypted backup can’t be restored from the browser uploader. Restore it with the CaveCMS command line on the server that holds its key. And after any restore, the app signs everyone out so you log back in as a restored user. If a page looks stale, clear your browser cache and sign in fresh.

Symptom

After a restore, you’re the “wrong” account.

Right after a restore, your login seems off. A password that should work is rejected, or the admin bar is missing on the public site, or you appear signed in as an old account.

Why: a restore replaces the users table, so your previous browser session points at data that just changed underneath it. Fixed in 0.2.6+. Restores now force a clean re-login.

Fix

Clear your browser cache (or use a fresh private window), reload, and sign in with the restored account’s email and password. To change your own password afterward, use Account → Change password in the admin.

Symptom

Your domain still shows your old site.

You opened your domain and a parking page, a host welcome page, or a leftover from a previous site comes up instead of CaveCMS, even though the app is started and healthy.

Why: the host is serving a stale index.html or a default .htaccess left in the domain’s public_html instead of handing the request to the Passenger app. A static file in the docroot wins over the app, so visitors never reach CaveCMS.

Fix

  1. In cPanel → File Manager, open the domain’s public_html and remove or rename any leftover index.html (or default .htaccess) the host placed there.
  2. In Setup Node.js App, confirm the app’s Application URL points at the right domain, so Passenger serves it from that docroot.
  3. Restart the app and reload your domain. Passenger now rewrites .htaccess on boot, so reload the domain once it’s back up.

The other half

When it’s a host setting, not CaveCMS.

A few things live with your hosting account, not the app. If you hit these, a short, specific request to your host clears them:

Stuck processes

After repeated crashes the account can hold wedged processes that only a virtual-environment restart clears. Ask: “Please reset (restart) my virtual environment to clear stuck processes.”

Memory limit

If the memory readout on Settings → Updates is tight and the site keeps dropping under normal use, ask to raise your plan’s memory to 2 GB.

Database connections

If “max_user_connections” persists with the app stopped and no lingering processes in phpMyAdmin, ask your host to clear stuck MySQL connections or raise the per-user connection limit for your database user.

Node version

CaveCMS needs Node 20.19+, 22.12+, or 23+. In Setup Node.js App, pick a supported Node version for the app; the installer also checks this up front.

Still stuck?

Most of it is one update away.

When you’re moving a site onto cPanel for the first time, the deploy runbook walks the full install-then-restore path. Comparing hosts? See the trade-offs.

Keep going

Related

Deploy to production

Take a site you built locally to a production server: fresh install, then restore your content over it. A verified, step-by-step runbook.

View→

Compare hosting

Self-host on a VPS, cPanel shared hosting, or your laptop, compared across cost, control, requirements, and AI-edit support.

View→

Documentation

Everything you need to start, run, and grow a CaveCMS site, written in plain language.

View→