# Debugging Common Bee Node Issues Using the Bee Dashboard Interface

> Quickly debug common Bee node issues like connectivity and storage with the Bee Dashboard. Visualize health, peers, and more through the intuitive web interface.

- Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm)
- Tags: how-to-guide
- Published: 2026-03-01

---

**The Bee Dashboard provides a React-based web interface that visualizes Bee node health, peers, postage stamps, and pinned content through the Bee REST API, enabling rapid identification of connectivity, storage, and network issues without manual API calls.**

The `ethersphere/awesome-swarm` repository highlights the Bee Dashboard as the primary tool for debugging Bee node operations. By transforming raw REST API responses into color-coded status cards and searchable tables, this interface eliminates the need for operators to hand-craft `curl` commands when diagnosing common Swarm network problems.

## How the Bee Dashboard Architecture Supports Debugging

The dashboard functions as a **single-page React application** that communicates directly with a running Bee node via HTTP. In [`src/setupProxy.ts`](https://github.com/ethersphere/awesome-swarm/blob/main/src/setupProxy.ts), the development server configures request forwarding to avoid CORS errors when the browser attempts to reach the local Bee API (default port `1633`).

State management is centralized in [`src/contexts/ApiContext.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/contexts/ApiContext.tsx), where React hooks (`useEffect`, `useState`) cache API responses and trigger refreshes on configurable intervals. This ensures the **Health**, **Peers**, and **Stamps** views always reflect the current node state without manual page reloads.

Visualization components like [`src/components/HealthCard.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/HealthCard.tsx) consume these cached states to render **Recharts** graphs and **Material-UI** tables. The [`HealthCard.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/HealthCard.tsx) component specifically aggregates the `/health` endpoint payload into a color-coded badge—green indicates a healthy node, while red signals immediate attention required.

## Step-by-Step Debugging Workflow with the Bee Dashboard

Follow this systematic approach to identify and resolve Bee node issues using the dashboard interface:

1. **Access the Dashboard** – Navigate to `http://localhost:3000` (or your hosted URL) while the Bee node process is active on the target machine.

2. **Verify Node Health** – Inspect the **Health** card, which queries `/health`. A status of `unreachable` or `low-disk-space` indicates infrastructure-level problems requiring immediate intervention.

3. **Analyze Peer Connectivity** – Open the **Peers** tab rendered by [`src/components/PeersTable.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/PeersTable.tsx). This lists all overlay addresses returned by `/peers`. A count of zero or rapidly dropping connections typically indicates NAT traversal failures or bootstrap node misconfiguration.

4. **Audit Postage Batches** – Check the **Stamps** view (backed by [`src/components/StampsList.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/StampsList.tsx)) which calls `/stamps`. Look for `balance: 0` or `usable: false` flags that prevent new content uploads.

5. **Review Pinned Content** – Navigate to the **Pins** screen, implemented in [`src/components/PinList.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/PinList.tsx), to inspect `/pins` responses. Entries stuck in `pinning` status for extended periods suggest storage corruption or insufficient disk I/O.

6. **Examine Resource Usage** – For performance issues, access the **Debug** panel if enabled, which surfaces `/debug/pprof` metrics for CPU and memory profiling.

## Common Bee Node Issues and Dashboard-Driven Solutions

| Issue | Dashboard Symptom | Resolution |
|-------|-------------------|------------|
| **Node not reachable** | Health card displays `unreachable` or API timeout errors | Verify the Bee process is listening on port `1633` and check firewall rules. |
| **Low disk space** | Health badge shows `disk space low`; Pins list contains error states | Free storage in the `--data-dir` directory or expand volume capacity, then restart Bee. |
| **Postage batch depleted** | Stamps view shows `balance: 0` or `batch not sufficient` warnings | Create a new batch via `bee batch create` and register it using the dashboard's "Add Batch" button. |
| **No peer connections** | Peers tab displays `0` entries | Confirm the `--bootnode` flag points to a live bootstrap node and open TCP/UDP port `1633` through NAT. |
| **Stuck pins** | Pins table shows persistent `status: pinning` | Execute `bee pin check` to force re-pinning, or clear corrupted chunks from the local datastore. |
| **High resource consumption** | Debug panel reveals elevated pprof metrics | Restart the node, upgrade to the latest Bee version, or allocate additional RAM/CPU to the host. |

## API Inspection Scripts for Manual Verification

When the dashboard indicates an anomaly, you can verify the underlying data using these browser console scripts that replicate the dashboard's API calls against `http://localhost:1633`.

### Check Node Health Status

```javascript
fetch('http://localhost:1633/health')
  .then(r => r.json())
  .then(data => console.log('Bee health →', data));

```

### List Connected Peers

```javascript
fetch('http://localhost:1633/peers')
  .then(r => r.json())
  .then(peers => {
    console.table(peers.map(p => ({
      address: p.address,
      network: p.network,
      uptime: p.uptime
    })));
  });

```

### Inspect Postage Batch Balances

```javascript
fetch('http://localhost:1633/stamps')
  .then(r => r.json())
  .then(batches => {
    batches.forEach(b => {
      console.log(`Batch ${b.batchID}: balance=${b.balance}, usable=${b.usable}`);
    });
  });

```

### Identify Stuck Pins

```javascript
fetch('http://localhost:1633/pins')
  .then(r => r.json())
  .then(pins => {
    const stuck = pins.filter(p => p.status !== 'pinned');
    console.log('Stuck pins →', stuck);
  });

```

### Automate Health Monitoring

```javascript
// Mimics the dashboard's auto-refresh behavior
setInterval(() => {
  fetch('http://localhost:1633/health')
    .then(r => r.json())
    .then(console.log);
}, 15000);

```

## Summary

- The **Bee Dashboard** serves as the visual layer for the Bee node's REST API, transforming JSON responses from endpoints like `/health`, `/peers`, `/stamps`, and `/pins` into actionable debugging interfaces.
- Key components including [`src/components/HealthCard.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/HealthCard.tsx), [`src/components/PeersTable.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/PeersTable.tsx), and [`src/contexts/ApiContext.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/contexts/ApiContext.tsx) handle the data fetching and visualization logic that operators rely on for rapid diagnostics.
- Common issues such as depleted postage batches, zero peer counts, and disk space shortages manifest as specific visual cues (red badges, empty tables, error statuses) that guide operators to precise fixes without manual log parsing.
- The [`src/setupProxy.ts`](https://github.com/ethersphere/awesome-swarm/blob/main/src/setupProxy.ts) configuration handles CORS and request forwarding, enabling secure browser-based access to local node APIs during troubleshooting sessions.

## Frequently Asked Questions

### How do I access the Bee Dashboard if my node runs on a remote server?

Ensure port forwarding is configured for `1633/tcp` on the remote host, then either run the dashboard locally with the proxy pointing to the remote IP, or deploy the dashboard build artifacts to a web server with CORS headers allowing the remote Bee API endpoint. The [`src/setupProxy.ts`](https://github.com/ethersphere/awesome-swarm/blob/main/src/setupProxy.ts) configuration can be modified to target remote hosts during development.

### Why does my Health card show "unreachable" even though the Bee process is running?

This typically indicates the dashboard cannot reach the Bee API due to firewall rules, incorrect port binding, or CORS restrictions. Verify that the node started successfully and is listening on `0.0.0.0:1633` (not just localhost), and that no browser extensions are blocking the cross-origin requests from the dashboard UI.

### What causes postage batches to show as "not sufficient" in the Stamps view?

A batch becomes insufficient when its balance drops to zero or its depth is inadequate for the current network conditions. The dashboard queries `/stamps` to display these values in [`src/components/StampsList.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/StampsList.tsx). You must create a new batch with sufficient BZZ tokens using the `bee batch create` command and refresh the dashboard to see the updated status.

### How can I clear stuck pins identified in the dashboard?

Navigate to the **Pins** screen in [`src/components/PinList.tsx`](https://github.com/ethersphere/awesome-swarm/blob/main/src/components/PinList.tsx) to identify chunks with `status: pinning`. From the command line, run `bee pin check` to force re-verification, or manually remove corrupted data from the node's `--data-dir` storage directory before restarting the Bee service.