# Troubleshooting Common Bee Node Connection and Performance Issues: A Complete Guide > Fix common Bee node connection and performance issues. This guide covers network blocks, P2P settings, and resource limits using tools from ethersphere/awesome-swarm. - Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm) - Tags: how-to-guide - Published: 2026-03-01 --- **Most Bee node connection failures and performance degradation stem from three core areas: network connectivity blocks, misconfigured P2P settings, and insufficient system resources, all of which can be diagnosed using the open-source tools cataloged in the `ethersphere/awesome-swarm` repository.** The `ethersphere/awesome-swarm` repository maintains a curated collection of community-built utilities designed to resolve the most frequent Bee node operational challenges. When your node fails to sync with the Swarm network or exhibits degraded upload speeds, systematic troubleshooting across network, configuration, and hardware layers is essential for restoring full functionality. ## Understanding the Three Layers of Bee Node Problems ### Network Connectivity Barriers DNS resolution failures, restrictive firewall rules, and missing port forwarding configurations prevent Bee nodes from reaching the Swarm overlay network. The node requires unobstructed access to establish P2P connections; when ports **1633**, **1634**, or **1635** are blocked inbound or outbound, peer discovery fails entirely. ### Bee Health and Configuration Errors Misconfigured Bee settings—such as incorrect `P2P` address bindings, insufficient `SWARM_API` resource allocations, or invalid postage batch configurations—cause timeout errors and synchronization stalls. These configuration mismatches manifest as `peer not reachable` messages in logs or persistent `storage sync stalled` warnings. ### System Resource Limitations CPU saturation, memory exhaustion, and disk I/O bottlenecks directly impact a node's ability to process chunk hashes, maintain peer tables, and execute upload/download operations. When the Bee process consumes over 80% of available CPU or when storage latency spikes during sync operations, network performance degrades proportionally. ## Essential Diagnostic Tools from the Awesome Swarm Ecosystem The `ethersphere/awesome-swarm` repository catalogs several specialized utilities that target specific failure modes. These community-maintained tools provide programmatic access to node health data, eliminating the need for manual log parsing. **Doctor Bee** is a lightweight Python script that pings the node's health endpoint and reports subsystem status. It quickly verifies the `/status` and `/health` APIs, showing whether the node is reachable and which subsystems (P2P, postage, storage) are failing. **Bee Dashboard** offers a React-based visual interface for monitoring peer counts, bandwidth utilization, and storage metrics. It provides real-time graphs of inbound/outbound connections, block heights, and replication lag, making it easy to spot a starving peer table. **Swarm CLI** serves as a command-line wrapper around the Bee REST API, enabling one-liners such as `swarm node status` or `swarm node peers` to fetch health data without custom scripting. **Beest** provides an interactive CLI toolkit for managing multiple Bee instances, with commands like `beest health` and `beest sync` that run checks in parallel across several machines, useful for large deployments. **Beekeeper** functions as a Kubernetes operator for managing clusters of Bee nodes, automating proper Service/Ingress configuration and ensuring required ports (1633, 1634, 1635) are exposed across the cluster. **Bee-AFS** implements a FUSE filesystem that mounts a Bee node locally, allowing you to monitor I/O latency directly from the OS and exposing disk bottlenecks that affect chunk storage. ## Step-by-Step Bee Node Troubleshooting Workflow Follow this systematic procedure to isolate and resolve connection and performance issues using the tools available in the `ethersphere/awesome-swarm` ecosystem. 1. **Verify basic node reachability** Test the node's HTTP interface with a simple cURL command: ```bash curl http://localhost:1633/status ``` If the request fails, run **Doctor Bee** to determine whether the HTTP server is down or firewalled: ```bash pip install doctor-bee doctor-bee http://127.0.0.1:1633 ``` 2. **Inspect peer statistics and connectivity** Check peer counts using either the **Bee Dashboard** (open `http://localhost:3000` and navigate to "Peers" → "Connected") or the **Swarm CLI**: ```bash swarm node peers ``` A low peer count (fewer than 5) typically indicates NAT or port-forwarding issues. Ensure ports 1633, 1634, and 1635 are allowed inbound and outbound through your firewall. 3. **Analyze system resource utilization** Monitor CPU and memory usage with `top` or `htop`, looking for the Bee process consuming over 80% of available CPU. Check disk I/O with `iostat -xz 1` while the node is syncing. If I/O is saturated, consider mounting a faster SSD or use **Bee-AFS** to benchmark raw filesystem latency. 4. **Review Bee logs for error patterns** Examine `/var/log/bee.log` or Docker logs for specific error messages such as `peer not reachable`, `postage batch error`, or `storage sync stalled`. These messages indicate which subsystem requires configuration adjustment. 5. **Execute fleet-wide health checks** For deployments with multiple nodes, use **Beest** to aggregate health data: ```bash beest health --all ``` This command collects each node's `/health` JSON output into a single table, highlighting outliers across your infrastructure. 6. **Apply targeted fixes** - Open necessary ports in your firewall or configure NAT forwarding. - Increase `SWARM_API` memory limits via the `--api-addr` flag or Docker environment variables. - Restart the node after configuration changes: `docker restart bee`. ## Summary - **Bee node connection issues** typically originate from network blocks, configuration errors, or resource constraints across three distinct layers. - The `ethersphere/awesome-swarm` repository provides specialized diagnostic tools including **Doctor Bee**, **Bee Dashboard**, and **Beest** to isolate specific failure modes. - **Ports 1633, 1634, and 1635** must remain open for proper P2P connectivity; low peer counts indicate NAT or firewall misconfigurations. - Systematic troubleshooting requires verifying HTTP reachability, inspecting peer statistics, monitoring CPU/RAM/disk I/O, and analyzing logs for specific error patterns like `storage sync stalled`. - For multi-node deployments, **Beekeeper** and **Beest** enable automated health checks and configuration management across clusters. ## Frequently Asked Questions ### Why is my Bee node showing zero peers despite being online? A peer count of zero indicates that your node cannot establish outbound P2P connections or accept inbound ones. Verify that ports 1633, 1634, and 1635 are forwarded through your NAT and allowed by your firewall. Use **Doctor Bee** to test connectivity to the `/status` endpoint, and check logs for `peer not reachable` errors that confirm network-layer blocks. ### How can I check if my Bee node has sufficient system resources? Monitor the Bee process using `htop` or `top` to ensure CPU usage remains below 80% during sync operations. Check disk I/O with `iostat -xz 1` while the node is actively uploading or downloading chunks. If you observe latency spikes, mount **Bee-AFS** to benchmark raw filesystem performance, or migrate your data directory to a faster SSD to eliminate storage bottlenecks. ### What is the fastest way to diagnose multiple Bee nodes in a Kubernetes cluster? Use **Beekeeper**, the Kubernetes operator specifically designed for Swarm deployments. It automates Service and Ingress configuration while ensuring required ports remain exposed across pods. For ad-hoc diagnostics across many nodes, install **Beest** and run `beest health --all` to aggregate `/health` endpoint data from every node into a single comparative table, instantly highlighting outliers requiring attention. ### Which tool should I use for real-time visualization of Bee node performance? **Bee Dashboard** provides the most comprehensive real-time visualization for single-node monitoring. This React-based interface displays live graphs of inbound and outbound bandwidth, connected peer counts, block heights, and storage utilization. Access it at `http://localhost:3000` (default configuration) and navigate to the Peers section to identify replication lag or connection starvation before they impact sync performance.