Troubleshooting Guide

Quick reference for common Made Open development issues. Each entry follows symptom, cause, fix.

Docker Issues

docker compose up fails immediately

Symptom: Cannot connect to the Docker daemon or docker: command not found.

Cause: Docker Desktop is not running.

Fix: Start Docker Desktop and wait for the engine to initialize before retrying.

Port conflicts on startup

Symptom: Bind for 0.0.0.0:XXXX failed: port is already allocated.

Cause: Another process is using one of the required ports.

Fix: Find and stop the conflicting process:

# Linux/macOS
lsof -i :4222
# Windows (PowerShell)
netstat -ano | findstr :4222

Then kill the process or stop the conflicting container with docker compose down.

Docker runs out of memory

Symptom: Containers exit with code 137 (OOM killed), or Supabase containers fail to start. Supabase alone pulls ~10 containers.

Cause: Docker Desktop default memory limit (2 GB) is too low.

Fix: Open Docker Desktop Settings > Resources > Memory and set to at least 6 GB. On WSL2, edit ~/.wslconfig:

[wsl2]
memory=8GB

Then restart WSL: wsl --shutdown.

docker compose --profile full up hangs

Symptom: The command stalls waiting for NATS to become healthy. Older versions of docker-compose.yml used a nc (netcat) health check that did not work reliably.

Cause: The NATS health check was changed to use HTTP /healthz on the monitoring port. If you have a stale compose file, the old check may hang.

Fix: Pull the latest docker-compose.yml from main. The current health check is:

healthcheck:
  test: ['CMD-SHELL', 'wget -qO- http://localhost:8222/healthz || exit 1']

If you need to bypass health checks temporarily: docker compose up -d --no-deps nats.

Supabase Issues

supabase start fails with port conflicts

Symptom: Error: port 54321 already in use (or 54322, 54323).

Cause: Another Supabase instance is already running -- typically a global install from a different project.

Fix:

supabase stop --all     # Stop all Supabase instances
supabase start          # Restart for this project

The project uses fixed ports configured in supabase/config.toml: API 54321, DB 54322, Studio 54323.

supabase start hangs pulling images

Symptom: The command stalls on Pulling images... for several minutes with no progress.

Cause: Docker pull is failing silently due to network issues, proxy configuration, or Docker Hub rate limits.

Fix: Pull the images manually to see actual errors:

docker pull supabase/postgres:15.1.1.61

If rate-limited, authenticate with Docker Hub: docker login.

supabase status -o env returns empty

Symptom: Running supabase status -o env prints nothing or only partial output, breaking scripts that extract keys.

Cause: Supabase services are not fully started or the CLI version is outdated.

Fix:

supabase status          # Check if all services show "HEALTHY"
supabase stop && supabase start   # Restart if unhealthy

If the CLI is old, upgrade: brew upgrade supabase/tap/supabase or scoop update supabase.

supabase db push errors on existing migrations

Symptom: ERROR: relation "xyz" already exists when running supabase db push.

Cause: The migration has already been applied. This is safe to ignore.

Fix: These errors are harmless. If you need a clean slate, run supabase db reset instead, which drops and recreates the database from all migrations.

Hub Issues

Hub crashes on start with missing env vars

Symptom: Error: SUPABASE_SERVICE_ROLE_KEY is required or Error: DATABASE_URL is required.

Cause: Environment variables are not set. The hub requires Supabase connection details.

Fix: Run the quickstart script to generate .env files automatically:

make quickstart
# or
bash scripts/quickstart.sh

Alternatively, copy .env.example to .env in the project root and fill in the values from supabase status -o env.

Hub can't connect to NATS

Symptom: NatsError: CONNECTION_REFUSED or Error connecting to nats://localhost:4222.

Cause: The NATS container is not running or has not passed its health check yet.

Fix:

docker compose up -d          # Start infrastructure
docker compose ps             # Verify nats shows "healthy"

If NATS is running but unhealthy, check its logs: docker compose logs nats.

Hub can't connect to Meilisearch

Symptom: MeiliSearchCommunicationError or ECONNREFUSED on port 7700.

Cause: Meilisearch is not running, or MEILI_URL / MEILI_MASTER_KEY are wrong.

Fix: Verify the container is up and the key matches:

docker compose ps              # Check meilisearch status
curl http://localhost:7700/health   # Should return {"status":"available"}

The default master key for local dev is dev-master-key (set in docker-compose.yml).

isolated-vm build failure on Windows

Symptom: npm ERR! gyp ERR! during pnpm install, specifically for the isolated-vm native addon.

Cause: isolated-vm requires a C++ compiler and Python 3 to build native V8 bindings.

Fix: Install the Visual Studio C++ Build Tools:

# Option 1: npm helper (run as Administrator)
npm install -g windows-build-tools

# Option 2: Install manually
# Open Visual Studio Installer → Modify → check "Desktop development with C++"

Make sure Python 3 is on your PATH. Then retry pnpm install.

Web Issues

Web app shows blank page

Symptom: The Next.js app loads at http://localhost:4100 but renders nothing. Browser console shows Supabase errors.

Cause: NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY are not set.

Fix: Add them to apps/web/.env.local:

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-key>

Get the anon key from supabase status -o env or run make quickstart to generate .env files.

Web app can't reach the hub

Symptom: API calls fail with network errors. The UI shows loading spinners indefinitely.

Cause: NEXT_PUBLIC_HUB_URL is not set or the hub is not running on port 4101.

Fix: Ensure the hub is running (pnpm hub, or make dev for hub + web together) and set the env var:

NEXT_PUBLIC_HUB_URL=http://localhost:4101

Node.js / pnpm Issues

pnpm install fails

Symptom: Unsupported engine or module resolution errors during install.

Cause: Wrong Node.js or pnpm version. The project requires Node.js >= 20 and pnpm >= 9.

Fix: Check your versions and upgrade if needed:

node -v    # Must be 20+
pnpm -v    # Must be 9+

Use nvm or fnm to manage Node.js versions. Install pnpm with corepack enable && corepack prepare pnpm@9 --activate.

import.meta errors at runtime

Symptom: SyntaxError: Cannot use 'import.meta' outside a module.

Cause: The package is missing "type": "module" in its package.json. All packages in this monorepo use ESM ("module": "NodeNext" in tsconfig).

Fix: Add "type": "module" to the affected package's package.json.

TypeScript: import type errors

Symptom: TypeScript errors like This import is a type-only import and must use 'import type'.

Cause: Strict NodeNext module resolution requires type-only imports to be explicit.

Fix: Change import { SomeType } to import type { SomeType } for types, interfaces, and type aliases that are not used as values.

General Recovery

Nuclear reset

When nothing else works, tear everything down and start fresh:

docker compose down -v       # Stop containers, delete volumes
supabase stop                # Stop all Supabase services
supabase db reset            # Recreate database from migrations
make quickstart              # Full setup from scratch

Health check

Run the built-in diagnostics:

make doctor                  # Checks Docker, Node, pnpm, Supabase, ports, connectivity
# or
bash scripts/made-open doctor

Viewing logs

make logs                    # Tail all dev container logs (docker compose logs -f)
make logs-test               # Tail test stack logs
docker compose logs nats     # Single service logs

For hub and web, check the terminal where pnpm dev / make dev is running. Both stream logs to stdout.