Restart or Repair the Dashboard

The QuickBox Pro v4 dashboard runs as a single Node.js systemd service called v4-dashboard.service. When the dashboard goes blank, shows a 502/503, or stops responding to logins, the fix is almost always one of three things: restart the service, re-run the dashboard update pipeline, or repair the underlying install. This page walks through each tier from lightest to heaviest so you can pick the right tool on the first try.

There is no `qb dashboard` command

QuickBox Pro does not ship a qb dashboard verb. Commands like qb dashboard restart or qb dashboard repair do not exist — if you typed one and got “command not found,” that is expected. The real commands are systemctl restart v4-dashboard and qb fix dashboard, both documented below.

Dashboard vs WSDashboard — know which one is broken

Users frequently conflate two different surfaces:

The v4 dashboard is the main QuickBox Pro web UI served from /opt/v4-dashboard. It is managed by the v4-dashboard.service systemd unit. Everything on this page is about that service.
WSDashboard (also called WSD or What’s Streaming Dashboard) is a module inside the v4 dashboard — it is not a separate service. If only the streaming panel is broken but the rest of the dashboard loads, skip this page and see WSDashboard troubleshooting.

If the entire dashboard will not load, you are in the right place.

Tier 1 — Restart the dashboard service

The fastest recovery. Use this first for any transient issue: blank page after a reboot, a hung request, or memory pressure after a long uptime.


# Check current state first
systemctl status v4-dashboard
 
# Restart the service
sudo systemctl restart v4-dashboard
 
# Confirm it came back up
systemctl status v4-dashboard

A healthy restart takes about 2–5 seconds. If systemctl status reports active (running) and the listener port (a value in the 3001–3099 range chosen at install time) is bound, the dashboard is back online. Reload your browser with a hard refresh to clear any cached 502 page.

systemctl restart is idempotent

Restarting the service does not touch your database, settings, or user data. It just re-launches the Node.js process. It is always safe to try first.

Tier 2 — Repair the dashboard with `qb fix dashboard`

If a restart alone does not clear the problem — typically after a failed update, a partial download, or a build that ends up in an inconsistent state — step up to the repair command.


qb fix dashboard

What it does

qb fix dashboard is a thin wrapper that re-runs the full v4 dashboard update pipeline (qb update dashboard). Specifically, it:

Re-downloads the latest dashboard source archive from central.quickbox.io
Re-runs the installer’s update script (/opt/v4-dashboard/etc/install/update-v4-dashboard.sh)
Rebuilds assets and restarts v4-dashboard.service at the end
Preserves your settings, database, and environment file (/etc/v4-dashboard/v4-dashboard.env)

It is the same code path that runs when the dashboard updates itself — just triggered on demand. Use it when a restart is not enough but you do not want to reinstall from scratch.

Use qb fix dashboard when

Blank page or partial UI after a recent dashboard update
Dashboard service starts but immediately exits
systemctl status shows 'exit-code' or 'failed' repeatedly
Dashboard version drifted out of sync with the CLI
Errors referencing missing dist files or corrupt assets

What it resolves

Re-downloads the complete dashboard source archive
Rebuilds Node.js bundles and static assets from scratch
Restarts v4-dashboard.service at the end of the pipeline
Resolves partial or interrupted updates
Brings the dashboard build back in sync with your CLI version

Preserves user data

qb fix dashboard is non-destructive. User accounts, installed applications, settings in system_configuration, and the dashboard database at /etc/v4-dashboard/data/db/qbpro.db are all preserved. It only replaces dashboard code and rebuilds assets.

Tier 3 — Full binary refresh with `qb fix version`

Reach for this only when both a restart and qb fix dashboard have failed, or when the CLI itself is misbehaving alongside the dashboard.


qb fix version

This forces a complete refresh of the QuickBox CLI binaries and then re-runs the dashboard update pipeline as part of the broader refresh. It is the heaviest option short of a reinstall and should not be your first move.

See qb fix for the full breakdown of what qb fix version touches.

Check the dashboard logs

The v4 dashboard logs through journald, tagged with the identifier v4-dashboard. There are also per-user operation logs written to disk whenever a package is installed, removed, or updated through the dashboard UI.

Service logs (journald)


# Tail the live log
sudo journalctl -u v4-dashboard -f
 
# Last 200 lines
sudo journalctl -u v4-dashboard -n 200
 
# Errors only since the last boot
sudo journalctl -u v4-dashboard -b -p err
 
# Logs from the last 15 minutes
sudo journalctl -u v4-dashboard --since "15 min ago"

Per-user operation logs on disk

Every install, remove, or update you trigger through the dashboard writes a dedicated log file:

opt/v4-dashboard/var/log/

└── {username}/

│ ├── package-install-{jobId}.log# Dashboard-triggered install output

│ ├── package-remove-{jobId}.log# Dashboard-triggered remove output

│ └── package-update-{jobId}.log# Dashboard-triggered update output

When you open a support thread, attach the relevant package-*.log file alongside journalctl -u v4-dashboard -n 200 output — together they give staff everything they need to triage.

Key files and paths

opt/v4-dashboard/# Dashboard install root

├── dist/# Compiled server bundle (dist/server.js)

├── var/log/# Per-user operation logs

├── var/run/# Runtime state

└── etc/install/# Install + update scripts invoked by qb fix dashboard

etc/v4-dashboard/# Dashboard configuration

├── v4-dashboard.env# Environment file loaded by the systemd unit

└── data/db/qbpro.db# Shared SQLite database (v3 + v4)

etc/systemd/system/v4-dashboard.service# Systemd unit definition (installed from the package)

The service runs as the dedicated qbxdashboard system user with the qbusers group so it can read user configs across the box. Do not edit the unit file by hand — qb fix dashboard will restore the shipped version.

Decision guide — which tier do I need?

Symptom

Dashboard was working, now shows 502/503 or hangs
Dashboard looks stale but loads; one module is broken
Dashboard was mid-update when the box lost power
Service keeps restarting in a loop
qb CLI commands themselves behave strangely alongside dashboard errors

Recommended action

Start with systemctl restart v4-dashboard
Restart first, then check journalctl for the stale module
Run qb fix dashboard to re-run the update pipeline cleanly
Check journalctl -u v4-dashboard for the crash reason before running qb fix dashboard
Escalate to qb fix version, then qb fix dashboard

Common scenarios

The dashboard returns 502 Bad Gateway

Nginx is up but the Node.js service is not listening. Run systemctl status v4-dashboard — if it is inactive or failed, restart it. If it keeps failing, tail journalctl -u v4-dashboard -n 100 to read the startup error, then escalate to qb fix dashboard.


systemctl status v4-dashboard
sudo systemctl restart v4-dashboard
# If still failing:
sudo journalctl -u v4-dashboard -n 100
qb fix dashboard

The dashboard loads but every page shows an error

The service is running but the build is broken. This usually happens when an update was interrupted. Skip the restart and go straight to qb fix dashboard to rebuild cleanly.

The dashboard is stuck on an old version

Your CLI updated but the dashboard pipeline did not finish. Run qb fix dashboard to re-trigger the update.

Only the streaming view is broken

That is a WSDashboard-specific issue, not a dashboard service issue. See WSDashboard troubleshooting — restarting v4-dashboard.service will not help if the streaming module’s configuration is the problem.

Best practices

Do

Start with systemctl restart v4-dashboard before anything heavier
Always check journalctl -u v4-dashboard before running a repair command
Attach journalctl output and the relevant package-*.log file when opening a support thread
Let qb fix dashboard finish — it downloads, rebuilds, and restarts in one pass
Confirm the v4 dashboard and WSDashboard are not being confused before triaging

Don't

Type qb dashboard restart — that command does not exist
Troubleshoot the v4 dashboard with php-fpm commands — it is Node.js, not PHP
Edit /etc/systemd/system/v4-dashboard.service by hand
Delete /opt/v4-dashboard manually — use the installer to recover
Jump straight to qb fix version when a restart would have worked

FAQ

No. QuickBox Pro has no qb dashboard verb. The real command is sudo systemctl restart v4-dashboard. If you need to rebuild the dashboard after a failed update, use qb fix dashboard instead.

systemctl restart v4-dashboard just relaunches the existing Node.js process — fast, non-destructive, fixes transient issues. qb fix dashboard re-runs the full dashboard update pipeline: it re-downloads the source archive, rebuilds assets, and restarts the service at the end. Use restart first; reach for qb fix dashboard when the build itself is broken.

Service logs go through journald. Tail them with sudo journalctl -u v4-dashboard -f. Per-user operation logs (installs, removes, updates triggered from the dashboard UI) are written to /opt/v4-dashboard/var/log/{username}/package-{action}-{jobId}.log.

No. It only replaces dashboard code and rebuilds assets. Settings in system_configuration, the SQLite database at /etc/v4-dashboard/data/db/qbpro.db, your environment file, and every installed application are preserved. It is safe to run whenever the dashboard is misbehaving.

That is a WSDashboard module issue, not a dashboard service issue. Restarting v4-dashboard.service or running qb fix dashboard will not help because the service itself is healthy — the streaming module needs its own configuration check. See the WSDashboard documentation.

Always v4-dashboard (or the fully qualified v4-dashboard.service). It runs as the qbxdashboard user in the qbusers group, with working directory /opt/v4-dashboard. The unit file lives at /etc/systemd/system/v4-dashboard.service.

Systemd will back off after five restarts within 60 seconds (the StartLimitBurst the unit ships with). Read the actual crash reason with sudo journalctl -u v4-dashboard -n 200 first — the logs will name the file or module that is failing. Once you know the root cause, run qb fix dashboard to rebuild cleanly, or escalate to the Discord support channel with the log excerpt attached.

Keep troubleshooting

Troubleshooting Hub

CLI-first triage playbook for the whole server.

qb fix reference

Every `qb fix` subcommand, including `fix dashboard` and `fix version`.

qb update reference

How dashboard updates flow through the release pipeline.

WSDashboard (Streaming)

If only the streaming module is broken, start here instead.

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support

Feature Previews

Community Configs

Active Discussions

Join Discord Server