Skip to main content

Most common Problems

GitHub-logo.png logo.png

Beszel Logo

Beszel Troubleshooting Guide

Below are common issues that you may encounter when setting up or running Beszel, along with suggested steps to diagnose and resolve them. Refer to the official Common Issues guide on the Beszel website for additional details.

 

First of all set your Agent/s to LogMode "debug" if you havent already.

Agent is not connecting

First, check the logs page in PocketBase at /_/#/logs to see if there's an identifiable error. The most common cause is a firewall blocking the connection request. You have two options to resolve this:

  • Add a firewall rule: Create an inbound rule on your agent system’s firewall(s) to allow TCP connections on the specified port. This includes checking iptables or any cloud provider firewall settings you may be using.
  • Use a tunneling or VPN solution: Software like WireGuard, Tailscale (video instructions), or Cloudflare Tunnel (instructions) can securely bypass firewall restrictions.

Another possibility is that you forgot to expose the container ports in your Docker configuration. Make sure the port is mapped and accessible.

To test connectivity, run:

telnet <agent-ip> <port>

If the connection is refused or times out, it indicates a networking or firewall problem.

Connecting hub and agent on the same system using Docker

If the hub runs in a normal bridged network mode, but the agent is using host network mode, add the system using host.docker.internal as the hostname, which resolves to the special IP used by the host system. (See the Getting Started guide for a complete docker-compose.yml example.)

  • Host mode for both hub and agent: You can use localhost as the hostname if both containers share host networking.
  • Bridge mode for both: Use the agent’s container_name if both are on the same Docker network, e.g. beszel-agent.

Finding the correct filesystem

By default, the agent tries to detect and monitor the root filesystem for disk stats. In a container, this may not work reliably, so it’s recommended to specify the filesystem via the FILESYSTEM environment variable. To locate the correct filesystem:

  • lsblk: Check under “NAME.”
  • df -h: Check under “Filesystem.”
  • sudo fdisk -l: Check under “Device.”

Docker container charts are empty or missing

If the container charts in Beszel are empty or don’t appear, you may need to enable cgroup memory accounting. To verify this, run docker stats. If you see zero memory usage, follow the guide here:

Enabling memory stats in Docker

This issue is common on certain Raspberry Pi or other ARM-based systems, but can also affect other environments where cgroup memory accounting is disabled by default.

Docker containers are not populating reliably

Upgrade to the latest Docker version if possible. There is a known bug in Docker 24 (and possibly earlier versions) that affects container stats. Although the agent includes a workaround, it may not completely resolve the issue.

Month / week records are not populating reliably

Beszel aggregates longer time periods (week/month) from shorter interval data. The agent must run uninterrupted for the entire interval to properly generate these records. If you pause/unpause the agent for more than a minute, you’ll lose continuity for that interval, causing incomplete data.

Back to top