====== Beszel Agent 401 Unauthorized ======

Beszel agent getting 401 Unauthorized errors when connecting to Beszel hub.

===== Symptom =====

beszel-agent logs show: `WARN WebSocket connection failed err="unexpected status code: 401"`

===== Cause =====

The beszel-agent is not on the same Docker network as beszel, preventing container name resolution. Using `network_mode: host` prevents the agent from resolving the beszel container name.

===== Fix =====

Change the beszel-agent configuration to use Docker networking instead of host networking.

**Incorrect configuration:**
```yaml
beszel-agent:
  network_mode: host  # This prevents container name resolution
  environment:
    HUB_URL: http://localhost:8090  # localhost doesn't work in Docker
```

**Correct configuration:**
```yaml
beszel-agent:
  networks:
    - folkzone_net  # Use Docker network
  environment:
    HUB_URL: http://beszel:8090  # Use container name
```

**Steps:**
  1. Edit docker-compose.yml
  2. Change `network_mode: host` to `networks: - folkzone_net`
  3. Change `HUB_URL: http://localhost:8090` to `HUB_URL: http://beszel:8090`
  4. Restart: `docker compose up -d beszel-agent`
  5. Verify connection: `docker compose logs beszel-agent`

===== Prevention =====

Always use Docker networking for inter-container communication. Avoid `network_mode: host` unless absolutely necessary for the specific use case.

===== See Also =====

  * [[folkzone:troubleshooting:start|Troubleshooting Index]]
  * [[folkzone:infrastructure:docker|Docker Infrastructure]]

Last updated: 2026-06-19
  * [[folkzone:start|Return to folkzone]]