Issue Troubleshooting (Windows / WSL 2)

This page covers the issues you are most likely to hit on Windows. Most of them are environment-level (Docker Desktop integration, WSL 2 networking, port conflicts) rather than node-level — node logs are still the best signal once the stack is up.

Docker Compose path (Track 1)

`docker compose: command not found`

You probably have the deprecated Python docker-compose (with a hyphen) installed instead of the v2 plugin (with a space). The current node tooling requires the v2 plugin. Fix:

On Windows, install or update Docker Desktop — recent versions ship the v2 plugin out of the box and expose docker compose inside WSL 2 when WSL Integration is enabled.
Inside WSL 2, verify with:
docker compose version

`docker` works in PowerShell but not in WSL 2

Open Docker Desktop → Settings → Resources → WSL Integration and toggle on integration for your Ubuntu distro, then click Apply & Restart. Re-open the WSL shell and re-run docker --version.

Port `53550` already in use

Either you have another process bound to it, or a previous docker compose run is still up. Fix: edit .env and pick a free port:

RPC_PORT=53560
EXPOSED_URL=http://localhost:53560

Then restart the stack:

docker compose down
docker compose up -d

If you want to find what is holding the port from inside WSL:

sudo lsof -i :53550

Postgres connection refused on first boot

Postgres takes a few seconds to become healthy. The node is wired with depends_on: condition: service_healthy, so this normally resolves itself. If it persists:

docker compose logs postgres
docker compose ps

If Postgres is crash-looping, the most common cause is leftover state from a prior incompatible run. Reset only the Postgres volume (this destroys chain data but keeps your identity):

docker compose down
docker volume rm demos_pgdata
docker compose up -d

Slow builds or strange filesystem behaviour

Move the repo out of /mnt/c/... and into the WSL 2 home directory (e.g. ~/node). The Windows-mounted drive is significantly slower than the native WSL 2 filesystem for builds, bind mounts, and Docker layer caching.

`EXPOSED_URL` warning at startup

EXPOSED_URL is set to a loopback/unroutable address is expected for local development. Peers will ignore your node, but RPC works locally. Set EXPOSED_URL to a reachable address only when you’re actually exposing the node.

Resetting everything

If you want a clean slate:

docker compose down -v   # destroys ALL named volumes (identity, chain data, dashboards)

This is irreversible. Back up demos_node_state first if you care about your .demos_identity.

Bare-metal path (Track 2, inside WSL 2)

The bare-metal path uses Bun, not Yarn or npm. If you see references to Yarn anywhere, they are stale and should be ignored.

`bun: command not found`

Install Bun inside the WSL 2 shell:

# Preferred: via Mise
curl https://mise.run | sh
mise use -g bun@latest

# Alternate: direct installer
curl -fsSL https://bun.sh/install | bash

Verify:

bun -v

Rebuilding dependencies from scratch

If the node won’t start after a git pull or you suspect corrupted dependencies:

rm -rf node_modules bun.lockb
bun install

Postgres sidecar issues (bare-metal)

The bare-metal ./run flow manages a Postgres sidecar in postgres_5332/. If the database is unreachable:

# From the project root
cd postgres_5332
./clean.sh
./start.sh

Then go back to the project root and ./run again. For the full bare-metal reference (every ./run flag, the install-deps script, identity generation), see INSTALL.md — Track 2.

Wrong env vars from old docs

If you copied an older .env from outdated documentation, replace these:

Old (wrong)	New (correct)
`SERVER_PORT=53550`	`RPC_PORT=53550`
`RPC_FEE=5` (single fee)	`RPC_FEE=1` + `NETWORK_FEE=1` + `BURN_FEE=1` (three components, default total = 3)

For the bare-metal path also set:

PG_HOST=localhost
PG_PORT=5332
TLSNOTARY_HOST=localhost

Where to look next

Run the Project (Windows) — main setup flow
WSL 2 Setup — install / verify WSL 2
INSTALL.md — canonical reference for both tracks
.env.example — every env var the node reads

Introduction

FAQ

Node Setup

Issue Troubleshooting

Issue Troubleshooting (Windows / WSL 2)

Docker Compose path (Track 1)

`docker compose: command not found`

`docker` works in PowerShell but not in WSL 2

Port `53550` already in use

Postgres connection refused on first boot

Slow builds or strange filesystem behaviour

`EXPOSED_URL` warning at startup

Resetting everything

Bare-metal path (Track 2, inside WSL 2)

`bun: command not found`

Rebuilding dependencies from scratch

Postgres sidecar issues (bare-metal)

Wrong env vars from old docs

Where to look next

​Issue Troubleshooting (Windows / WSL 2)

​Docker Compose path (Track 1)

​docker compose: command not found

​docker works in PowerShell but not in WSL 2

​Port 53550 already in use

​Postgres connection refused on first boot

​Slow builds or strange filesystem behaviour

​EXPOSED_URL warning at startup

​Resetting everything

​Bare-metal path (Track 2, inside WSL 2)

​bun: command not found

​Rebuilding dependencies from scratch

​Postgres sidecar issues (bare-metal)

​Wrong env vars from old docs

​Where to look next

Issue Troubleshooting (Windows / WSL 2)

Docker Compose path (Track 1)

`docker compose: command not found`

`docker` works in PowerShell but not in WSL 2

Port `53550` already in use

Postgres connection refused on first boot

Slow builds or strange filesystem behaviour

`EXPOSED_URL` warning at startup

Resetting everything

Bare-metal path (Track 2, inside WSL 2)

`bun: command not found`

Rebuilding dependencies from scratch

Postgres sidecar issues (bare-metal)

Wrong env vars from old docs

Where to look next