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.
Most Beszel common issues and fixes depend on three root causes:
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.
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:
4. If you can't reach the port, add a firewall rule to allow TCP traffic to it. Or, instead of exposing it publicly, tunnel the connection using WireGuard, Tailscale, Cloudflare Tunnel, or Pangolin.
A "Failed to authenticate" error during setup typically means the key or token was copied incorrectly, rather than a network problem.
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:
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:
After saving this file, run:
In the web UI, when adding the system, set Host / IP to /beszel_socket/beszel.sock instead of localhost.
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.
telnet agent-ip port from a separate device to confirm the port actually answers.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.
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:
For rootless Docker setups, the standard socket path won't work; you need the user-specific path instead:
Update the compose file to mount that path and set DOCKER_HOST:
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:
If logs show an AppArmor denial, add:
If services still don't appear, also mount the systemd private socket:
Confirm systemd is version 243 or newer, since older versions don't support the ListUnitsByPatterns method Beszel relies on:
Test D-Bus accessibility directly:
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.
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:
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:
Append these parameters to the end of the existing line; do not add a new line:
Save the file and reboot to apply the change:
After reboot, verify accounting is active:
This resolves both native docker stats output and Beszel's container charts simultaneously.
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:
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.
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:
Restart the container after adding this volume, and TLS verification should pass without disabling checks entirely.
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.
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:
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.
Usually, a blocked port or unreachable WebSocket endpoint; check firewall rules and test with telnet agent-ip port.
Because of disabled cgroup memory accounting or a socket permission issue on rootless Docker setups.
Yes, but the proxy must support WebSocket connections and must not apply gzip compression to text/event-stream responses.