Skip to Content
DocsTroubleshooting QuickBox Pro

QuickBox Troubleshooting Hub

QuickBox Pro ships with a CLI-first toolchain and a graphical dashboard, so most incidents can be resolved in minutes when you follow the same flow our help manual and qb manpage document. 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, help manual, API key, or widgets, we mean the interface that lives at https://yourserver/index.php , not your account on v3.quickbox.io.

Stay aligned with the qb manpage

Diagnose from the CLI, confirm in the dashboard

Start with qb help for context, run the fix/clean utilities that mirror the help manual, then reopen 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

Mirror what the help manual describes

Every command above maps one-to-one with the translated help manual (dashboard → System → Help Manual). Skim the section titles—Options, Software, Multi User Software, Fix Database—and cross-reference the CLI Reference to understand what each qb subcommand touches before you run it.

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 Licenses view or run qb manage api again to confirm the handshake succeeded.

License & Activation Flow

  1. Check status in the dashboard: On your server’s dashboard (https://yourhost/index.php ), open Dashboard → Licenses and confirm the state is Active. Suspended or expired keys will block CLI actions until billing is resolved.
  2. Audit seat usage: The same Licenses view shows which activations consume seats. Deactivate retired servers from the dashboard or by running qb manage api -o deactivate on the host.
  3. Rotate API keys when needed: Generate a fresh key under Dashboard → API Keys. Apply it with qb manage api -k qbp_new_key and rerun the installer flags if you are automating deploys.
  4. Regenerate telemetry: If widgets stay stale, run qb manage telemetry -o on so the dashboard can see live health pings.

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 on-box dashboard (index.php) renders the same data described in help_manual.php. Widgets such as Service Control (srvCtrl_card.php/srvCtrl_list.php) and the Package Management Center (pmc.php) read directly from your server’s database, so missing tiles or stale stats 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 in the manual can be installed by non-admins. Reference the Multi User Software list and adjust availability via Dashboard → User Groups before asking users to reinstall.
  • Admin-installed software: Items such as fail2ban, rclone, rutorrent, or wireguard must be installed by an administrator (qb install software_name). Consult the Admin Installed Software matrix; standard users will continue to see these as read-only until granted.

Use the navigation helpers

Within the dashboard, the Help page includes quick links (lang navigation.php) to widgets, settings, and system panels. If a widget fails to load, reload the Help page to confirm translations were loaded and session data is valid.

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.

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 IDs from the Help Manual page. 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

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.

Changelog

See what shipped in the latest release cycle.

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 in the Help Manual can be installed without admin help. Assign the application to a group via Dashboard → User Groups and confirm the user belongs to that group before asking them to 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 IDs from the Help Manual; staff monitors the Discord channels continuously.

Getting Support the QuickBox WayUsing the v3 Dashboard