QuickBox Troubleshooting Hub

Troubleshooting in QuickBox Pro lives where the feature lives. Each dashboard and page owns the triage for the data it shows — the System Dashboard for server health and diagnostics, the App Dashboard for a specific application, the Streaming Dashboard for playback issues, and so on. This hub is the map: it gets your diagnostics collected the fast way, then routes you to the page that owns your symptom. A full qb CLI toolchain sits behind all of it for anyone who prefers the terminal.

Start by gathering diagnostics from your System Dashboard — it is the quickest, no-terminal way to capture everything support needs. Then use the routing map below to jump to the page that owns your issue, or run the matching qb utility from the CLI Reference.

Gather diagnostics the fast way

The preferred way to collect evidence for a support thread is your server’s System Dashboard — no terminal needed. Open it from the sidebar under Dashboard → System Dashboard (admin access required), then:

1. Quick snapshot: click Copy diagnostics in the top-right command bar. It copies a readable live snapshot — CPU, memory, disk, network, vnStat status — to your clipboard. Paste it into your Discord thread. This covers most first replies.
2. Full report: scroll to the bottom of the page to the Diagnostics panel and use the Copy / .txt / .json / Bundle buttons for a redacted report that is safe to share publicly.
3. Full detail (when support asks): in the same panel, open the Full detail menu and choose Download bundle for the complete, unredacted report. It carries your hostname and addresses, so send it in a DM to QuickBox support, not a public channel.

See System Monitoring → Diagnostics for the full walkthrough of each export and what it masks.

Where to troubleshoot

Troubleshooting is spread across the pages that own each feature. Match your symptom to the page that has the data and controls for it:

The rest of this page covers the server-wide lanes — licensing, install environment, and database health — plus the complete CLI diagnostics toolkit.

Rapid Response Checklist

Most issues fall into one of four buckets—license, install, dashboard cache, or database state. Run these commands (in order) on the affected server so you have a clean baseline before digging deeper.

qb help                       # Refresh available commands and software names
qb update quickbox            # Pull the latest fixes bundled with your release
qb fix version                # Grabs latest stable release and reupdates QuickBox files
qb clean memory               # Clear caches to free resources before reloading services
qb fix database               # Repair DB symlinks and prune duplicate software rows
qb manage api -o deactivate   # Reset the local activation handshake
qb manage api -k qbp_NEW_KEY  # Re-bind the server to your active license

License & Activation Flow

1. Check status on the dashboard: On your server’s dashboard, open System Administration → API Settings to confirm API credentials are active and, if you use it, telemetry is on. Suspended or expired keys will block actions until billing is resolved.
2. Audit your activations: The servers activated on your license are listed in your QuickBox account, under Licenses in the sidebar at quickbox.io/dashboard/licenses. See Servers and activations. Deactivate a retired server’s local activation by running qb manage api -o deactivate on the host.
3. Rotate API keys when needed: Generate a fresh key on your account at quickbox.io/dashboard/api-keys, then apply it with qb manage api -k qbp_new_key (or in the dashboard’s API Settings page).
4. Check telemetry: Telemetry is off by default on new installs. If your account shows the server as offline or its health data is stale, turn telemetry on from the API Settings page or run qb manage telemetry -o on. Your license and updates work without it.

Installation & Environment Issues

QuickBox expects a minimal, up-to-date Debian/Ubuntu install with root access during setup. Reproduce these prep steps whenever you encounter permission errors, missing dependencies, or partial upgrades.

sudo -i                      # Enter a root shell before running qbpro
apt-get -y update && apt-get -y upgrade
curl -sL "https://github.com/QuickBox/pro-v3/raw/refs/heads/main/qbpro_v3" > qbpro
chmod +x qbpro && ./qbpro -u USER -p 'PASSWORD' -k 'API_KEY'

• Permission denied? Ensure qb commands run via the QuickBox user environment. The installer configures /etc/shells; deviating from Bash can break qb.
• Port conflict? Follow the installer logs to identify busy ports (80/443 for nginx, 3001-3099 for the dashboard). Stop the conflicting service or rerun the installer with alternate port flags.
• System clutter? Use the clean helpers documented in the CLI Reference: qb clean system_logs -o 7 -u username to purge stale logs and qb clean qb_logs -u username for dashboard traces.

Dashboard & Database Health

Your dashboard’s Application Control panel and Package Management catalog read directly from your server’s database, so missing applications or stale version badges point to local database or cache issues.

• Duplicate or missing software rows: Run qb fix database. It auto-detects SQLite vs MySQL, repairs the legacy /opt/quickbox/db/qbpro.db symlink (pointing at /opt/quickbox/config/db/qbpro.db) on v3-only servers and skips that step when the v4 dashboard is installed, and prunes duplicate entries by keeping the newest ID per user/software pair.
• Multi-user permissions: Only software marked as multi-user can be installed by non-admins. Reference the Multi User Software list and adjust availability via User Management → Groups before asking users to reinstall.
• Admin-installed software: Items such as fail2ban, rclone, netdata, or wireguard must be installed by an administrator (from Package Management, or qb install software_name). Consult the Admin Installed Software matrix; standard users will see these as read-only until granted.

System load creeping with kernel writeback workers pegged

If your server’s load average climbs slowly over hours or days while the box stays responsive and no application is busy, check the kernel writeback workers. When a control group dies (a service restart, a daily restart cron, or repeated updates), the kernel re-homes every cached inode that cgroup owned. On a box with a very large inode cache that cleanup can livelock: two kernel worker threads spin near 100% of a CPU and the backlog stops draining.

• The fingerprint: two kworker threads pegged for hours - kworker/...+inode_switch_wbs and kworker/...+events_unbound - seen with top, not ps (a lifetime average hides it). Application activity is normal; only these kernel workers are hot.
• Confirm it: run qb fix writeback. The read-only check needs no root, samples the workers, and reports clear, livelock, or unsupported with the dying-cgroup, inode, and cache counters behind the verdict.
• Clear it: run qb fix writeback --apply (root). It syncs and releases unreferenced dentries and inodes so the drain can finish, never touching in-use files. The same check and apply live on the dashboard under System Dashboard > Hardware Health > Writeback cleanup card.

CLI Diagnostics Toolkit

The CLI remains the fastest way to validate that services, users, and quotas are configured properly. Start with the featured commands below, all of which map directly to the qb manpage sections and the CLI Reference.

Autocomplete & keyboard tips

Support & Live Assistance

QuickBox support is 100% Discord-based. Opening a thread keeps everything in one place—logs, screenshots, and staff replies—and mirrors how we triage internally. Review the Support Playbook before posting so staff has the context they need.

FAQ