Common Issues

If your issue is not listed here, please search our GitHub Issues and Discussions for a solution. You can also try asking in the community-run Matrix room.

Agent is not connecting

Check the logs page in PocketBase (/_/#/logs) for information about the error. One of the two communication directions described below needs to be working.

The agent initiates a WebSocket connection to the hub at /api/beszel/agent-connect, so make sure this endpoint is accessible. If using a reverse proxy, make sure it's able to proxy WebSocket connections.

The hub initiates a TCP connection to the agent, so make sure the port on the agent system is not blocked.

1. Check any active firewalls, like iptables, and your cloud provider's firewall settings if applicable. Add an inbound rule allowing TCP connections to the port.
2. Alternatively, use software like WireGuard, Tailscale (video instructions), Cloudflare Tunnel (instructions), or Pangolin (instructions) to securely bypass the firewall.

You can test connectivity by running telnet <agent-ip> <port> from another device on your network.

Connecting hub and agent on the same system using Docker

When connecting to a local agent, localhost will not work because the containers are in different networks. The recommended way to connect them is to use a unix socket.

Click to view complete docker-compose.yml config including local agent

IMPORTANT

This configuration should work out of the box, but you must follow these steps when adding the system in the web UI:

1. Update the KEY and TOKEN environment variables with your public key and token, then restart the agent:

docker compose up -d

2. Use the unix socket path as the Host / IP in the web UI:

/beszel_socket/beszel.sock

docker-compose.yml

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    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>"

Click to view instructions for running docker compose

NOTE

If you prefer to set up containers in a different way, please feel free to do so.

1. Install Docker and Docker Compose if you haven't already.

2. Copy the docker-compose.yml content.

3. Create a directory somewhere to store the docker-compose.yml file.

mkdir beszel
cd beszel

4. Create a docker-compose.yml file, paste in the content, and save it.

nano

nano docker-compose.yml

vim

vim docker-compose.yml

emacs

emacs docker-compose.yml

vscode

code docker-compose.yml

5. Start the service.

docker compose up -d

Real time stats not working / changes not saving

Check if you have gzip or some other encoding being applied at the proxy level.

The web UI needs compression disabled on anything with content type text/event-stream for SSE to work properly.

If you use Coolify, uncheck "Enable gzip compression" in the hub service settings.

Finding the correct filesystem

Specify the filesystem/device/partition for root disk stats using the FILESYSTEM environment variable.

If not set, the agent will try to find the partition mounted on / and use that. This may not work correctly in a container, so it's recommended to set this value. Use one of the following methods to find the correct filesystem:

• Run lsblk and choose an option under "NAME."
• Run df -h and choose an option under "Filesystem."
• Run sudo fdisk -l and choose an option under "Device."

Self-signed certificate issues in Docker

When running Beszel in a Docker container and connecting to services that use self-signed certificates, you may encounter TLS certificate verification errors.

The error typically looks like this:

tls: failed to verify certificate: x509: certificate signed by unknown authority

To resolve this issue, you need to provide your custom CA certificate to the Docker container:

1. Save your CA certificate file (e.g., custom-ca.crt) on the host system
2. Mount it into the container's certificate directory:

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

After implementing this solution, connections to services with self-signed certificates should work properly.

Docker container charts are empty or missing

If container charts show empty data or don't appear at all, you may need to enable cgroup memory accounting. To verify, run docker stats. If that shows zero memory usage, follow this guide to fix the issue:

https://akashrajpurohit.com/blog/resolving-missing-memory-stats-in-docker-stats-on-raspberry-pi/

Docker stats missing with rootless agent

See issue #640 where tercerapersona posted a solution. Use the correct socket path for your user and enable cgroup CPU delegation if CPU stats are missing.

Docker containers are not populating reliably

Upgrade your Docker version on the agent system if possible. There is a bug in Docker 24, and possibly earlier versions, that may cause this issue. We've added a workaround to the agent to mitigate this issue, but it's not a perfect fix.

Month / week records are not populating reliably

Records for longer time periods are created by averaging stats from shorter periods. The agent must run uninterrupted for a full set of data to populate these records.

Pausing/unpausing the agent for longer than one minute will result in incomplete data, resetting the timing for the current interval.