# How to Troubleshoot SwarmForge Dashboard Connection Issues: A Complete Guide

> Resolve SwarmForge dashboard connection issues by verifying the dashboard-url file, checking port 64002 for conflicts, and clearing stale state. Your complete troubleshooting guide.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-09-01

---

**SwarmForge dashboard connection issues typically stem from the `dashboard-url` file not being created, a port conflict on the default `64002` port, or a crashed HTTP server—verify the file exists, check `dashboard.log`, and clear stale `.swarmforge` state to resolve.**

The SwarmForge dashboard is a lightweight web UI that starts automatically when you run the host (`./swarm` or `bb swarmforge.bb`). Understanding how the host communicates with this dashboard—and where that communication can break down—is essential for quickly diagnosing problems. This guide walks through the exact mechanisms in `unclebob/swarm-forge` and provides practical fixes based on the source code.

## How the SwarmForge Dashboard Connection Works

The connection between host and dashboard relies on three core components working in sequence.

### Core Components

| Component | Source File | Primary Function |
|-----------|-------------|------------------|
| **Web server launcher** | `swarmforge/scripts/pack_web.bb` | Starts HTTP server, writes reachable URL to disk |
| **Host orchestrator** | `swarmforge/scripts/swarmforge.bb` | Waits for URL file, prints it to console |
| **Dashboard UI** | [`swarmforge/scripts/pack/dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack/dashboard.html) | Static UI that calls backend APIs on same port |

### Connection Sequence

1. **Host invokes `pack_web.bb`** — when you start `./swarm`, the host script launches the web server
2. **Server binds to local port** — default `64002` on `127.0.0.1`, stored in `dashboard-port` variable
3. **URL persistence** — `write-dashboard-url!` creates `<state-dir>/.swarmforge/dashboard-url` containing the URL
4. **Host reads and displays URL** — `swarmforge.bb` uses `wait-for-file` (5-second timeout) to read the URL and print it

If the `dashboard-url` file never appears, the host aborts with: *"No visible Terminal surfaces; use the dashboard."*

## Common Failure Modes and Diagnosis

### No URL Printed, Host Appears to Stall

**Root cause:** `pack_web.bb` never successfully writes the `dashboard-url` file.

**Verify:**

```bash
ls .swarmforge/dashboard-url

```

If missing, the web server failed to start. Check the runtime log:

```bash
tail -n 30 .swarmforge/dashboard.log

```

### Dashboard Loads But Stays Blank

**Root cause:** Server started on a different port than recorded, or the browser cannot reach the reported port.

**Verify:** Open the exact URL printed by the host, then compare with the port in `dashboard.log`. Check for port mismatches.

### Stale URL After Previous Crash

**Root cause:** Old `dashboard-url` file from a prior run; new server may fail due to port already in use.

**Fix:** Remove the stale file and restart:

```bash
rm .swarmforge/dashboard-url
./swarm

```

### "Connection Refused" in Browser

**Root cause:** HTTP server process died (crash, OOM, missing Java runtime for the underlying HTTP kit).

**Verify:** Examine `dashboard.log` for stack traces. The server logs startup confirmation or fatal errors here.

### Port Conflict on Default 64002

**Root cause:** Another process occupies the default port.

**Verify and fix:**

```bash
lsof -i :64002

# or

netstat -tlnp | grep 64002

```

Override the port via environment variable (read by `pack_web.bb` via `System/getenv`):

```bash
export SWARMFORGE_DASHBOARD_PORT=65000
./swarm

```

## Step-by-Step Troubleshooting Checklist

Follow this ordered sequence to isolate the problem.

### 1. Confirm the Dashboard URL File Exists

```bash
cat .swarmforge/dashboard-url

```

Expected output: `http://127.0.0.1:64002` (or your custom port)

### 2. Inspect the Dashboard Server Log

```bash
tail -n 30 .swarmforge/dashboard.log

```

Look for:
- `Server started on http://...` — confirmation of successful launch
- Any exception stack traces — indicates startup failure

### 3. Validate the Server Is Actually Listening

```bash
lsof -iTCP -sTCP:LISTEN -P | grep $(cat .swarmforge/dashboard-url | awk -F: '{print $3}')

```

No output means the server process exited or never started.

### 4. Force a Clean State Reset

```bash
rm -rf .swarmforge
./swarm

```

This removes old URLs, logs, and pending request queues.

### 5. Override the Default Port

```bash
export SWARMFORGE_DASHBOARD_PORT=65500
./swarm

```

`pack_web.bb` uses this value when calling `run-server` if present.

### 6. Run the Automated Test Suite

The repository includes Playwright integration tests that validate the full startup flow:

```bash
cd test/dashboard
npm install
npx playwright test

```

Failures here indicate server-side problems or missing dependencies.

## Advanced Diagnostic Techniques

### Manually Start the Dashboard Server

Bypass the `./swarm` wrapper to isolate server issues:

```bash
cd /path/to/swarm-forge
bb swarmforge/scripts/pack_web.bb

```

Direct output shows the actual bind address and any immediate crashes.

### Inspect Pending API Requests

When the UI loads but shows "no tasks," check for unconsumed requests:

```bash
ls .swarmforge/dashboard/requests/pending
cat .swarmforge/dashboard/requests/pending/<request-id>.request

```

These JSON blobs are created by `pack_dashboard_request.bb` and fetched by the UI via `GET /api/chat` or `POST /api/ui` endpoints.

### Review the Host Orchestrator Logic

In `swarmforge.bb`, the key function is `wait-for-file` on the `dashboard-url` path. If this times out after 5 seconds, the host aborts. Understanding this timeout helps distinguish between slow startup vs. complete failure.

## Key Source Files Reference

| File Path | Purpose | Relevant Functions/Variables |
|-----------|---------|------------------------------|
| `swarmforge/scripts/pack_web.bb` | HTTP server lifecycle | `dashboard-port`, `write-dashboard-url!`, `run-server` |
| `swarmforge/scripts/swarmforge.bb` | Host dashboard coordination | `wait-for-file`, URL printing logic |
| `swarmforge/scripts/pack_dashboard_request.bb` | API endpoints for UI | `/api/chat`, `/api/ui` handlers |
| [`swarmforge/scripts/pack/dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack/dashboard.html) | Static dashboard interface | Frontend JavaScript calling backend |
| [`test/dashboard/dashboard.spec.js`](https://github.com/unclebob/swarm-forge/blob/main/test/dashboard/dashboard.spec.js) | Integration validation | Playwright startup tests |
| `.swarmforge/dashboard.log` *(runtime)* | Server stdout/stderr | Startup confirmation, crash traces |
| `.swarmforge/dashboard-url` *(runtime)* | IPC between host and UI | Single-line URL file |

## Summary

- **The `dashboard-url` file is the linchpin** — if missing, the web server in `pack_web.bb` never completed startup
- **Check `.swarmforge/dashboard.log`** first for server-side error messages
- **Port conflicts on `64002`** are common; use `SWARMFORGE_DASHBOARD_PORT` to relocate
- **Stale state** from crashed runs causes misleading failures; `rm -rf .swarmforge` provides clean slate
- **Playwright tests** in `test/dashboard/` offer automated validation of the full pipeline

## Frequently Asked Questions

### Why does SwarmForge say "No visible Terminal surfaces; use the dashboard"?

The host in `swarmforge.bb` timed out waiting for the `dashboard-url` file. This means `pack_web.bb` failed to start the HTTP server or write the file. Check `dashboard.log` for the underlying error and verify no port conflict exists.

### Can I run the dashboard on a different port?

Yes. Set the `SWARMFORGE_DASHBOARD_PORT` environment variable before starting. The `pack_web.bb` script reads this via `System/getenv` and passes it to `run-server` instead of the default `64002`.

### Where are dashboard errors logged?

Runtime server output goes to `.swarmforge/dashboard.log` in your working directory. This includes successful startup messages, port binding confirmation, and any stack traces from crashes.

### What if the dashboard URL file exists but the browser cannot connect?

The server likely crashed after writing the file, or a firewall blocks the loopback port. Verify with `lsof` that a process is still listening on the reported port, then check `dashboard.log` for exit reasons.