QuickBox Troubleshooting Hub

QuickBox Pro is managed primarily from its dashboard, with a full qb CLI toolchain behind it for diagnostics and automation. Most incidents can be resolved in minutes: confirm the symptom in the dashboard, then run the matching qb fix/clean utility documented in the CLI Reference. Use this page as your live playbook to validate licensing, repair installs, and reset multi-user software access before escalating to the community. Need per-app context? Jump to the Applications catalog for health checks by software family.

Scope: your server, your API key

Everything here targets the QuickBox Pro instance that you deployed on your own hardware. When we mention the dashboard, settings, API key, or system panels, we mean the QuickBox Pro dashboard served from your own server (at https://your-server-ip or your domain), not your account on v3.quickbox.io.

Dashboard first, CLI to repair

Spot it in the dashboard, fix it with qb

Confirm the symptom in the dashboard, then run the matching fix/clean utility from the CLI and reload the dashboard for visual confirmation. The sections below link directly to the docs you need most often while troubleshooting.

Open CLI Reference

Application Guides

Fresh Install Checklist

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

Know what each command touches

Cross-reference the CLI Reference to understand what each qb subcommand touches — install/remove, multi-user access, database repair — before you run it. You can also run qb help on the host for inline command and software listings.

Seat & heartbeat reminders

Licenses deactivate automatically if the heartbeat stops responding or your seat usage exceeds the plan. After updating the API key, open the dashboard’s API Settings page or run qb manage api again to confirm the handshake succeeded.

License & Activation Flow

Check status on the dashboard: On your server’s dashboard, open System Administration → API Settings to confirm API credentials and telemetry are active. Suspended or expired keys will block actions until billing is resolved.
Audit seat usage: Seat usage and activations live on your QuickBox account at v3.quickbox.io/dashboard/api-keys. Deactivate a retired server’s local activation by running qb manage api -o deactivate on the host.
Rotate API keys when needed: Generate a fresh key on your account at v3.quickbox.io/dashboard/api-keys, then apply it with qb manage api -k qbp_new_key (or in the dashboard’s API Settings page).
Regenerate telemetry: If health pings stay stale, re-enable telemetry from the API Settings page or run qb manage telemetry -o on so the dashboard sees live health data.

Heartbeat expectations

QuickBox pings your license every few minutes. Temporary outages self-heal once the heartbeat resumes; repeated failures mean the API key on disk does not match the dashboard, or there is indeed a critical issue on your server. Reapply the key and rerun qb update quickbox or qb fix version to stay current.

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/3000). 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.

Fresh installs only

Mixing QuickBox with pre-configured services often leads to unsupported states. If you inherited a server with existing stacks, back up your data and reinstall on a fresh VM before re-running qbpro.

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 /srv → /opt symlink if needed, 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, rutorrent, 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.

Reload after a stale render

If a panel fails to load or shows stale data, hard-refresh the dashboard page to clear cached state. If the whole dashboard will not load, see Restart or Repair the Dashboard.

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 at your fingertips

Hit Tab×Tab after qb, any command, or a software name to reveal completions instantly. It works for users, software, and nested commands.

Autocomplete & keyboard tips

Autocomplete shortcuts

Press Tab×Tab after qb, a command, or a software name to trigger the built-in autocomplete (from the quickbox completion script). It suggests commands, subcommands, usernames, and software names dynamically.
Use it with nested commands too, e.g., qb manage wireguard then Tab×Tab to see WireGuard actions.
When exploring, type qb help then tap Tab×Tab to list available help topics.

qb help

Display help information for any command

qb help [software]

Learn more →

qb user

Manage dashboard users and permissions

qb user [action] -u username

Learn more →

qb clean

Clean logs, caches, and temporary files

qb clean [type] -u username

Learn more →

qb fix

Repair common issues and reset configurations

qb fix [component]

Learn more →

qb update

Update QuickBox components and system

qb update [component]

Learn more →

qb manage

System configuration - API keys, database, backups

qb manage [component]

Learn more →

qb transfer

Manage the peer allowlist for inter-instance transfers

qb transfer peer-allow <ip>

Learn more →

Remember qb help [software]

Need the command syntax for a specific app? Execute qb help jellyfin (or any software slug) to see installer flags, user access, and dashboard pointers without leaving the terminal.

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.

Before posting in Discord

Include your QuickBox version, the output of qb update quickbox, and any error text from the dashboard or service logs. Never share full license keys; redact after the first four characters (e.g., QBPRO-1234---****).

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

Additional references

Restart or Repair the Dashboard

Tiered recovery for the v4 dashboard service.

Cancel & Report

Stop a stuck dashboard job and optionally notify admins.

Getting Started Guide

Re-run prerequisite steps for clean installs.

CLI Reference

Explore every qb command grouped by category.

Application Guides

Per-app health checks, ports, and recovery steps.

FAQ

Deactivate the old activation with qb manage api -o deactivate, rerun the installer, then bind the new API key using qb manage api -k qbp_new_key. Finish by running qb update quickbox so the dashboard reflects the rebuilt host.

Only software listed under Multi User Software can be installed without admin help. Assign the application to a group via User Management → Groups and confirm the user belongs to that group before they install it from Package Management (or run qb install <software>).

Run qb fix database. It repairs the `/srv/quickbox/inc/constants.php` symlink, detects whether you are on MySQL or SQLite, and prunes duplicate software_information rows by deleting the oldest IDs. If no duplicates exist, the tool reports that no action was taken.

Switch to the QuickBox user or root shell (sudo -i) before running qb. Confirm /etc/shells still lists Bash for that user. If you changed the shell, switch it back to `/bin/bash` to restore compatibility.

Join our Discord server and open a support thread. Share sanitized logs, the output of qb update quickbox, and any error text from the dashboard or service logs; staff monitors the Discord channels continuously.