Debugging Guide

Tools and techniques for diagnosing issues across the Equa stack

Debugging Guide

Last Verified: February 2026

This guide covers the debugging tools and techniques available for each layer of the Equa platform — frontend, backend, database, and the AI gateway.

Frontend Debugging (equa-web)

Browser DevTools

• React DevTools: Install the React Developer Tools browser extension to inspect component trees, props, state, and hooks.
• Immutable.js Formatter: Install Immutable.js Object Formatter for Chrome. Enable “Custom Formatters” in DevTools Settings. This makes Immutable.js objects readable in the console (used in some legacy Redux state).
• Network Tab: Monitor API calls to /api/* — the webpack dev server proxies these to equa-server on port 3000. Check request/response payloads and status codes here.

Source: equa-web/README.md (lines 47-50)

Webpack Dev Server

The dev server runs on port 8080 and proxies /api/* to http://localhost:3000. If API calls fail:

1. Check that equa-server is running on port 3000
2. Check the Network tab for the actual request URL and response
3. Verify the proxy configuration in the webpack config

Source Maps

equa-web builds with source maps enabled (sourceMap: true in tsconfig.json). You can set breakpoints directly in TypeScript files using the browser DevTools Sources tab.

Backend Debugging (equa-server)

Node.js Inspector

Start the API server with the Node.js inspector enabled:

cd ~/Documents/repos/equa-server
yarn start:debug

This runs node --inspect --require ts-node/register scripts/api.ts. Open chrome://inspect in Chrome to attach the debugger.

Source: equa-server/package.json script start:debug

IDE Debugging (VS Code / WebStorm)

For debugging directly from your IDE, use these Node.js arguments with ts-node:

--require ts-node/register/transpile-only

In VS Code, add a launch configuration:

{
  "type": "node",
  "request": "launch",
  "name": "equa-server",
  "args": ["modules/api/scripts/api.ts"],
  "runtimeArgs": ["--require", "ts-node/register/transpile-only"],
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal"
}

Source: equa-server/README.md (lines 39-41)

Express Session Debugging

To debug session-related issues (login, auth, cookie problems):

DEBUG=express-session yarn start:dev

This enables verbose Express session logging to stdout.

Source: equa-server/README.md (lines 109-113)

Winston Logging

equa-server uses Winston for application logging (configured in equa-server/modules/common/src/). Log levels follow the standard Winston hierarchy: error, warn, info, verbose, debug, silly.

Check the console output when running yarn start:dev for log messages from the application.

Database Debugging

TypeORM Query Logging

Enable SQL query logging by adding to your .env:

DATABASE_LOGS=query,error

This tells TypeORM to print every SQL query and any errors to the console. Useful for debugging slow queries, missing data, or unexpected query patterns.

Source: equa-server environment variable configuration

Direct Database Access

Connect to the PostgreSQL container directly:

docker exec -it equa-postgres psql -U postgres -d equa

Useful psql commands:

Command	Purpose
\dt	List all tables
\d table_name	Describe a table’s columns and types
\di	List all indexes
SELECT count(*) FROM organization;	Check row counts
\q	Quit psql

Checking Migration State

equa-server uses TypeORM’s auto-synchronization in development (DATABASE_SYNC environment variable). If the schema is out of sync:

1. Stop the server
2. Drop and recreate the database: docker-compose down && docker-compose up -d
3. Run yarn init:db to reinitialize

For production, SQL migration scripts live in equa-server/modules/persistence/lab/sql/migrations/.

Gateway Debugging (equabot)

macOS Unified Logs

When the equabot gateway runs as the macOS menubar app, logs go to the macOS unified logging system. Query them with:

./scripts/clawlog.sh

This script queries unified logs for the Equabot subsystem. It supports follow/tail/category filters.

Source: equabot/CLAUDE.md macOS logs section

Process Inspection

Check if the gateway is running:

launchctl print gui/$UID | grep equabot

Check the gateway port:

lsof -i :18789

Source: equabot/CLAUDE.md gateway debugging notes

WebSocket Debugging

To debug WebSocket connections between equa-web and the gateway:

1. Open browser DevTools -> Network tab -> filter by “WS”
2. Look for the WebSocket connection to ws://127.0.0.1:18789
3. Click on it to see individual frames (messages sent/received)
4. Check for connection errors or unexpected disconnects

Common Issues

Symptom	Cause	Fix
Error: listen EADDRINUSE :3000	Port 3000 occupied — another process on equa-server’s port	Run ps -p $(lsof -ti :3000) -o command= to identify. If next-server, kill it; always use npm run dev for command-center-so (binds to 3001, not 3000)
equa-web API calls return HTML instead of JSON	Something other than equa-server on port 3000	Run ps -p $(lsof -ti :3000) -o command= — should show ts-node. Kill any conflicting process, start equa-server with yarn start:dev, then restart equa-web
Error: listen EADDRINUSE :8080	Previous equa-web process still running	lsof -i :8080 to find PID, then kill <PID>
digital envelope routines::unsupported on equa-web	OpenSSL 3.x incompatibility with Webpack 4	Verify yarn start includes NODE_OPTIONS='--openssl-legacy-provider' (set automatically in package.json)
error engine required: node >=22.12.0	Wrong Node version for equabot	nvm use 24 before running equabot commands
Docker compose fails to start	Docker Desktop not running	Start Docker Desktop and wait for initialization
ECONNREFUSED 127.0.0.1:5432	PostgreSQL container not running	cd equa-server && docker-compose up -d
ECONNREFUSED 127.0.0.1:3000 from equa-web	equa-server not started	Start equa-server first: cd equa-server && yarn start:dev
yarn: command not found	Yarn not installed	npm install -g yarn
pnpm: command not found	pnpm not installed	npm install -g pnpm
Hot reload stops working (equa-web)	Webpack file watcher or cache issue	Stop and restart yarn start
API calls return 401	Session expired or cookie not set	Log in again; check that equa-server and equa-web are on the expected ports
Storybook won’t start on port 6006	Previous Storybook process	lsof -i :6006 to find and kill the process

Log Locations

Service	Log Destination	How to View
equa-server	stdout (console)	Terminal where yarn start:dev is running
equa-web	stdout (console) + browser console	Terminal + browser DevTools Console tab
PostgreSQL	Docker container logs	docker logs equa-postgres
equabot-gateway (dev)	stdout (console)	Terminal where gateway was started
equabot-gateway (macOS app)	macOS unified logs	./scripts/clawlog.sh
Storybook	stdout (console)	Terminal where npm run storybook is running
command-center-so	stdout (console)	Terminal where npm run dev is running (port 3001)

Useful Debug Commands

# Check what's running on all Equa ports
lsof -i :3000 -i :3001 -i :5432 -i :8080 -i :18789 -i :18791 -i :6006

# Identify what's on port 3000 (equa-server vs command-center-so)
ps -p $(lsof -ti :3000 2>/dev/null | head -1) -o command= 2>/dev/null
# Should show "ts-node" for equa-server, "next-server" for command-center-so

# View PostgreSQL container status
docker ps | grep equa-postgres

# Tail equa-server logs (if running in background)
tail -f /tmp/equa-server.log

# Kill all Equa processes
pkill -f "equa-server.*start:dev"
pkill -f "equa-web.*webpack"
pkill -f "equabot.*gateway"
pkill -f "storybook"
pkill -f "command-center-so.*next"