Skip to content

Troubleshooting

This guide helps you diagnose and resolve common qbee-connect errors. If you encounter a problem during authentication, connection establishment, or general operation, this guide covers the most frequently encountered problems with step-by-step diagnostic solutions.

Login and Authentication Issues

You click the verification link in the login dialog but no browser window opens.

Possible Cause: Your system's default browser is not configured, or the desktop environment cannot handle URL open requests.

Tip

  1. Note the verification URL displayed in the login dialog.
  2. Open your preferred browser manually and enter the verification URL in the address bar.
  3. Enter the user code shown in the dialog (format: XXXX-XXXX) on the Qbee authorization page.
  4. Complete authentication in the browser — qbee-connect will detect the approval automatically.

Login times out / code expires

The login dialog closes or shows an error indicating the device code has expired before you could complete authentication in the browser.

Possible Cause: The user code has a limited lifetime. If you don't complete browser authentication before it expires, the login attempt fails.

Tip

  1. Check your network connection — ensure you can reach https://www.app.qbee.io in your browser.
  2. Close and relaunch qbee-connect to generate a new user code.
  3. Complete the browser authentication promptly after the code appears.

Each user code is time-limited. If the code expires, you must restart qbee-connect to get a new one.

Logged out unexpectedly (401 error)

You were using qbee-connect normally, then the login dialog reappears unexpectedly.

Possible Cause: Your access token expired and the refresh token could not obtain a new one. This triggers an automatic re-authentication flow.

Tip

  1. Complete the login flow again using the new verification link and user code.
  2. qbee-connect automatically detects HTTP 401 responses and prompts re-authentication — no manual action is needed beyond completing the login.

This is normal behavior. Access tokens have a limited lifetime, and refresh tokens expire after a maximum of 7 days — a fresh login is then required.

Wrong account / wrong devices shown

After logging in, you see devices from the wrong Qbee tenant account.

Possible Cause: You are authenticated under a different tenant account than intended.

Tip

  1. Look for the Account dropdown in the pagination bar at the bottom of the device table.
  2. Select the correct account from the dropdown.
  3. The device table will refresh with the selected account's devices.

The account dropdown is only visible if you have access to two or more Qbee tenant accounts. If you only have one account, the dropdown does not appear.

Cannot switch accounts

You don't see an account switcher dropdown anywhere in the interface.

Possible Cause: Account switching is only available when you have previously logged in with credentials that have access to multiple Qbee tenant accounts.

Tip

  1. Verify your Qbee user account has access to more than one tenant account.
  2. If you recently gained access to a second account, log out and log back in so qbee-connect can fetch your updated account list.
  3. Once two or more accounts are available, the Account dropdown appears in the pagination bar.

Connection Issues

Connection fails immediately

You click Connect but the connection fails right away with an error.

Possible Cause: The remote device is offline, or the specified remote port is incorrect.

Tip

  1. Check the Online column in the device table — a green indicator means the device is connected to the Qbee platform.
  2. If the device shows as offline (red indicator), wait for the device agent to reconnect, or investigate the device directly.
  3. Verify the Remote Port in the connection dialog matches a service actually listening on the remote device.
  4. Verify the Remote Addr is correct (defaults to 127.0.0.1 for services running on the device itself).

Connection errors are displayed in a notification popup. Read the error message carefully — it often indicates the specific failure reason.

Port already in use

Connection fails with an error message containing 'address already in use'.

Possible Cause: Another application (or another qbee-connect tunnel) is already listening on the local port you specified.

Tip

  1. Choose a different Local Port in the connection dialog.

  2. Alternatively, identify and close the process using the conflicting port:

    Linux / macOS:

    lsof -i :PORT_NUMBER

    Windows:

    netstat -ano | findstr :PORT_NUMBER

  3. Leave the Local Port field blank to let qbee-connect automatically assign an available port.

Connection drops after a while

A previously working connection stops functioning.

Possible Cause: The remote device went offline, or there was a network interruption between your machine, the Qbee relay, or the device.

Tip

  1. Check the device's Online status in the device table.
  2. If the device is offline, the tunnel cannot function — wait for the device to reconnect.
  3. Check your own network connectivity to https://www.app.qbee.io.
  4. Close the broken connection and re-establish it once the device is back online.

Cannot connect to service after tunnel is established

The tunnel shows as active in qbee-connect, but your client application (SSH, browser, VNC, etc.) cannot reach the service through the tunnel.

Possible Cause: The target service is not running on the remote device at the specified port.

Tip

  1. Verify the service is actually running on the remote device at the configured Remote Port.
  2. Confirm the Remote Addr matches where the service is listening (usually 127.0.0.1).
  3. Make sure your client application is connecting to the correct Local Port and Local Addr shown in the active connections list.
  4. Check the Protocol (TCP vs UDP) matches what the service expects.

The active connections view shows the full tunnel mapping in the format tcp: 127.0.0.1:2222 → 127.0.0.1:22. Use the local side of this mapping in your client application.

Slow connection

The connection works but performance is noticeably slow.

Possible Cause: All traffic is routed through the Qbee relay infrastructure. Latency depends on the geographic distance between your machine, the Qbee relay servers, and the remote device.

Tip

  1. Ensure your local network connection is stable and has adequate bandwidth.
  2. Contact support@qbee.io — enterprise customers can request additional relay infrastructure deployed closer to their devices to reduce latency.

Device List Issues

No devices shown

The device table is empty after logging in.

Possible Cause: You are not logged in, or your Qbee account has no devices registered.

Tip

  1. Check that you are logged in — if the login dialog appears, complete the authentication flow.
  2. Verify in the Qbee.io console that your account has devices registered.
  3. If you have multiple accounts, check the Account dropdown to ensure you have selected the correct tenant.

Device shows as offline

A device appears in the table but the Online column shows a red indicator.

Possible Cause: The Qbee device agent on the remote device is not running or has lost connectivity to the Qbee platform.

Tip

  1. Check that the Qbee agent is running on the remote device.
  2. Verify the remote device has network connectivity to the Qbee platform.

You cannot establish connections to offline devices. The device must be online (green indicator) before a tunnel can be created.

Search returns no results

You search for a device but the table shows no matches even though you know the device exists.

Possible Cause: The search may be using the wrong search mode, or the search term doesn't match due to case sensitivity.

Tip

  1. Check the search mode dropdown — options are Device name, Group, and Tag.
  2. Make sure the search mode matches the type of value you are searching for.
  3. Note that search is case-sensitive — ensure your search term matches the exact casing of the device name, group, or tag.
  4. Clear the search field to see all devices, then refine your search.

Pagination not working

Pagination controls don't seem to navigate through devices, or the page indicator looks wrong.

Possible Cause: UI state may be stale, or the items-per-page setting may need adjustment.

Tip

  1. Try changing the items per page value in the pagination bar.
  2. Use the navigation arrows to move between pages.
  3. If the issue persists, log out and log back in to refresh the device list.

UI and Display Issues

Window doesn't appear

You launched qbee-connect but no window is visible on screen.

Possible Cause: The application may have started minimized to the system tray.

Tip

  1. Look for the qbee-connect icon in your system tray:
    • Linux: top-right panel or system tray area
    • macOS: menu bar at the top of the screen
    • Windows: taskbar notification area (click the up arrow to expand hidden icons)
  2. Right-click (or click on macOS) the tray icon and select Show to restore the window.

See System Tray for details on tray behavior.

System tray icon missing

After closing the window, you cannot find the qbee-connect icon in the system tray.

Possible Cause: Not all Linux desktop environments support system tray icons. Some minimal or tiling window managers do not include a system tray area.

Tip

  1. Check whether your desktop environment supports the system tray / notification area.
  2. On Linux, desktop environments like GNOME, KDE, and Xfce support system tray icons. Some tiling window managers (i3, Sway) may require additional configuration.
  3. If your environment does not support system tray, avoid closing the window — instead, minimize it using your window manager.
  4. Relaunching qbee-connect will open a new window.

Application won't start

qbee-connect fails to launch, possibly with an error about missing libraries.

Possible Cause: On Linux, the application requires graphics libraries that may not be installed.

Tip

  1. If you built from source on Linux, ensure the following build dependencies were installed:

    sudo apt install -y libgl1-mesa-dev xorg-dev

  2. Check that your system meets the system requirements.

  3. Try launching from a terminal to see any error output:

    ./qbee-connect

Installation Issues

Windows installer fails

The Windows installer fails to complete.

Possible Cause: The installer requires administrator privileges to write to the Program Files directory.

Tip

  1. Close the installer if it is still running.
  2. Right-click the .msi installer file.
  3. Select Run as administrator.
  4. Follow the on-screen prompts to complete the installation.

Linux package dependencies missing

Package installation fails with dependency errors on Linux.

Possible Cause: Required system libraries or dependencies are not installed.

Tip

  1. Debian / Ubuntu:

    sudo apt-get install -f

  2. Fedora / RHEL:

    sudo dnf install qbee-connect

  3. Retry installing the qbee-connect package.

macOS security warning

macOS displays a security warning when you try to open qbee-connect.

Possible Cause: Gatekeeper is blocking the app because it was downloaded from the internet.

Tip

  1. In the security dialog, click Open to proceed.
  2. If no dialog appears, right-click (or Control-click) the qbee-connect app in Finder.
  3. Select Open from the context menu.
  4. Click Open in the confirmation dialog.

After opening the app once, macOS remembers your choice and will not prompt again.

Getting More Help

If the solutions above don't resolve your issue:

  • Qbee Documentation: docs.qbee.io — official Qbee platform documentation
  • Qbee Support: Contact support@qbee.io for help with platform or account issues, to report bugs, or to request features

When reporting an issue, include:

  1. Your operating system and version
  2. The qbee-connect version (found in File → About)
  3. The error message (if any)
  4. Steps to reproduce the problem

See Also

Intent Document
Log in to qbee-connect Managing the Application → Authentication
Switch between accounts Managing the Application → Authentication
Use the system tray Managing the Application → System Tray
Browse my devices Devices & Connections → Finding Devices
Open a connection to a device Devices & Connections → Creating Connections
Understand how tunneling works Overview → How qbee-connect Works
Install qbee-connect and connect to your first device Getting Started