Debugging Common Bee Node Issues Using the Bee Dashboard Interface

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, 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, 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 consume these cached states to render Recharts graphs and Material-UI tables. The 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. 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) 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, 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

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

List Connected Peers

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

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

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

// 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, src/components/PeersTable.tsx, and 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 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}