Beszel is popular because it’s lightweight and reduces complexity, but that simplicity means the few things that can go wrong tend to feel extra confusing when they do. This guide shows you the Beszel common issues and fixes, from registration failures to silent alert delivery problems, so you can get your dashboard back to green fast.

For a full Beszel initial setup, you can see this tutorial on self-hosting Beszel for VPS and Docker monitoring.

Understanding Beszel Common Issues and Fixes

Most Beszel common issues and fixes depend on three root causes:

• Broken network paths between the hub and agent.
• Docker socket or permission mismatches.
• Misconfigured notification URLs.

Beszel’s architecture relies on a hub, the web UI and database, talking to lightweight agents installed on each monitored system, and any break in that chain surfaces as one of the symptoms covered below.

Before changing configs, check Beszel’s hub admin panel at /_/#/logs, it usually names the exact error.

Why Beszel Agent Registration Fails

Beszel supports two connection directions, and knowing which one applies to your setup solves most registration problems.

In WebSocket mode, the agent initiates the connection to the hub at /api/beszel/agent-connect, so that endpoint must be reachable and any reverse proxy in front of it must support WebSocket proxying.

In SSH mode, the hub opens a TCP connection out to the agent, so the port on the agent machine must accept inbound traffic.

1. Check the hub admin panel logs at /_/#/logs for the specific error message.

2. If in SSH mode with iptables -P FORWARD DROP on the hub host, either switch to WebSocket mode or allow forwarded packets.

3. Test connectivity from another device on the network:

telnet <agent-ip> <port>

4. If the port is unreachable, add an inbound firewall rule allowing TCP traffic to that port, or tunnel the connection with WireGuard, Tailscale, Cloudflare Tunnel, or Pangolin instead of exposing it publicly.

A “Failed to authenticate” error during setup typically means the key or token was copied incorrectly, rather than a network problem.

Key and Token Mismatch Between Beszel Hub and Agent

Every agent needs a matching KEY and TOKEN pair issued by the hub, and pasting a stale value is one of the Beszel common issues and fixes reported by self-hosters.

Update the agent’s environment variables to match what the hub generated, then restart the container fully:

docker compose up -d

If hub and agent run on the same host as separate Docker containers, localhost will not resolve between them because they sit on different container networks; use a Unix socket instead.

Here’s the full working docker-compose.yml for a local hub and agent setup:

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    environment:
      APP_URL: http://localhost:8090
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - ./beszel_socket:/beszel_socket
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: /beszel_socket/beszel.sock
      HUB_URL: http://localhost:8090
      TOKEN: <token>
      KEY: "<key>"

After saving this file, run:

mkdir beszel && cd beszel
nano docker-compose.yml
# paste the config above, update APP_URL, KEY, and TOKEN, then save
docker compose up -d

In the web UI, when adding the system, set Host / IP to /beszel_socket/beszel.sock instead of localhost.

Blocked Network Paths in Beszel

Firewall rules are a leading cause of agents that never appear online, and this is another entry on the list of Beszel common issues and fixes worth checking first.

Make sure the agent’s port is open, check both the server’s own firewall (iptables) and any firewall rules set by your cloud provider.

• Add an inbound rule for the agent’s port on both the OS firewall and the cloud provider’s security group.
• Run telnet agent-ip port from a separate device to confirm the port actually answers.
• If opening a public port feels risky, tunnel through WireGuard, Tailscale, Cloudflare Tunnel, or Pangolin instead.

For teams that prefer not to manage firewall rules manually, running Beszel on a properly configured Linux VPS with default network policies removes a whole category of these connectivity issues.

Docker Containers Not Detected by Beszel

If Docker containers don’t show up in the dashboard, it’s usually a socket permission problem or a Docker version bug.

First, verify the socket is mounted correctly in your compose file:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

For rootless Docker setups, the standard socket path won’t work; you need the user-specific path instead:

docker context ls
# note the ENDPOINT under "rootless", typically unix:///run/user/<UID>/docker.sock

Update the compose file to mount that path and set DOCKER_HOST:

services:
  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ${XDG_RUNTIME_DIR}/docker.sock:/var/run/docker.sock:ro
    environment:
      KEY: "HUB PUB KEY"

If CPU stats still show zero, turn on cgroup CPU delegation for rootless Docker.

Docker 24 and maybe older versions have a bug that makes containers appear inconsistently. Beszel has a partial workaround, but updating Docker is the better long-term fix.

Systemd-based service monitoring has its own checklist. Mount the D-Bus socket:

services:
  beszel-agent:
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket:ro

If logs show an AppArmor denial, add:

security_opt:
  - apparmor:unconfined

If services still don’t appear, also mount the systemd private socket:

volumes:
  - /var/run/systemd/private:/var/run/systemd/private:ro

Confirm systemd is version 243 or newer, since older versions don’t support the ListUnitsByPatterns method Beszel relies on:

systemctl --version

Test D-Bus accessibility directly:

dbus-send --system --dest=org.freedesktop.systemd1 --type=method_call --print-reply /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager.ListUnits

Bezel Missing Historical Data

If real-time stats work but weekly or monthly charts look empty, the agent probably restarted mid-interval. Beszel builds those long-term charts by averaging short-interval data, so any restart longer than a minute breaks that average and leaves a gap.

Keeping the agent running continuously is the only real fix, and this is one of the Beszel common issues and fixes people notice only weeks after setup when they check historical trends.

If real-time stats or settings won’t save, the problem is usually gzip compression on your reverse proxy breaking the live update connection. In Coolify, uncheck “Enable gzip compression” in the hub’s service settings. On other proxies, turn off compression for text/event-stream responses.

Docker Stats and Cgroup Accounting Issues in Beszel

Empty or missing Docker container charts are a cgroup memory accounting issue rather than a Beszel misconfiguration, and it’s one of the more frequently searched Beszel common issues and fixes.

Run this directly on the host to confirm:

docker stats

If memory usage reads zero for every container, cgroup memory accounting is disabled at the OS level, which is common on Raspberry Pi. Fix it by editing the boot config file commonly /boot/cmdline.txt, or /boot/firmware/cmdline.txt:

cat /boot/firmware/cmdline.txt

Append these parameters to the end of the existing line; do not add a new line:

cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1

Save the file and reboot to apply the change:

sudo reboot

After reboot, verify accounting is active:

docker info | grep -i cgroup

This resolves both native docker stats output and Beszel’s container charts simultaneously.

Validate Beszel Sockets, Permissions, and Clocks

Too many alerts or missing notifications usually depend on how the Shoutrrr URL is set up; that’s the tool Beszel uses to send alerts. You configure notification channels under Settings > Notifications, but alerts also need to be turned on separately for each system in the systems table. If a channel is set up correctly but never enabled on a system, you won’t get any alerts from it, with no error shown.

1. Check the URL format for your service carefully. Discord, Telegram, Slack, ntfy, and Pushover each need fields in a different order. One wrong field and the alert just won’t send.

2. For Telegram and Discord, make sure your bot token and chat/channel ID are still valid. If a token gets revoked, alerts fail silently with no error shown.

3. To stop getting too many alerts, adjust the threshold for each metric instead of using the defaults. This matters most for CPU and disk alerts on servers with unpredictable usage spikes.

4. If you’re using Authelia in front of the hub, versions 4.39.15 and newer need an authn_strategies block added to the config. Without it, you may get stuck in a login loop that blocks access to the dashboard:

server:
  endpoints:
    authz:
      forward-auth:
        implementation: 'ForwardAuth'
        authn_strategies:
          - name: 'CookieSession'

Getting notification delivery right is one of the last steps in resolving Beszel common issues and fixes, since a monitoring tool that can’t alert you is only half useful.

Self-Signed Certificates and TLS Errors in Beszel

TLS verification errors like x509: certificate signed by unknown authority show up when Beszel’s container tries to reach a service using a self-signed certificate.

Fix it by mounting your custom CA certificate into the container:

volumes:
  - /path/to/custom-ca.crt:/etc/ssl/certs/custom-ca.crt:ro

Restart the container after adding this volume, and TLS verification should pass without disabling checks entirely.

Long-Term Stability for Self-Hosted Monitoring

Most Beszel common issues and fixes come from the server itself, not the software; restrictive firewall defaults, low storage, or no root access make every issue above harder to fix.

Keep monitoring simple and reliable by running Beszel on a stable PerLod Linux VPS with full root access, so you can change firewall rules, fix Docker socket permissions, and adjust cgroup settings yourself instead of fighting provider restrictions.

Good backups matter too; with enough storage and root access, you can safely restore the hub’s database if an update or interrupted agent run damages your historical data.

If you’re also running other lightweight monitoring alongside Beszel, the same infrastructure principles apply to tools like Uptime Kuma, which shares similar socket and network dependency patterns.

Conclusion

Almost every Beszel problem, failed agent registration, missing Docker stats, gaps in historical data, or alerts that don’t arrive, depends on a few things:

• Blocked network paths.
• Socket or permission mismatches.
• Bad notification URLs.

Use these exact Beszel common errors and fixes steps, and hosting Beszel on a stable server with root access to stop many of these problems from coming back.

We hope you enjoy this guide on Beszel common issues and fixes.

For more detailed information, check the Beszel official common issues documentation.

FAQs