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:

Check that equa-server is running on port 3000
Check the Network tab for the actual request URL and response
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:

Stop the server
Drop and recreate the database: docker-compose down && docker-compose up -d
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:

Open browser DevTools -> Network tab -> filter by “WS”
Look for the WebSocket connection to ws://127.0.0.1:18789
Click on it to see individual frames (messages sent/received)
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"

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

Debugging Guide

Debugging Guide

Frontend Debugging (equa-web)

Browser DevTools

Webpack Dev Server

Source Maps

Backend Debugging (equa-server)

Node.js Inspector

IDE Debugging (VS Code / WebStorm)

Express Session Debugging

Winston Logging

Database Debugging

TypeORM Query Logging

Direct Database Access

Checking Migration State

Gateway Debugging (equabot)

macOS Unified Logs

Process Inspection

WebSocket Debugging

Common Issues

Log Locations

Useful Debug Commands

​Debugging Guide

​Frontend Debugging (equa-web)

​Browser DevTools

​Webpack Dev Server

​Source Maps

​Backend Debugging (equa-server)

​Node.js Inspector

​IDE Debugging (VS Code / WebStorm)

​Express Session Debugging

​Winston Logging

​Database Debugging

​TypeORM Query Logging

​Direct Database Access

​Checking Migration State

​Gateway Debugging (equabot)

​macOS Unified Logs

​Process Inspection

​WebSocket Debugging

​Common Issues

​Log Locations

​Useful Debug Commands

Debugging Guide

Frontend Debugging (equa-web)

Browser DevTools

Webpack Dev Server

Source Maps

Backend Debugging (equa-server)

Node.js Inspector

IDE Debugging (VS Code / WebStorm)

Express Session Debugging

Winston Logging

Database Debugging

TypeORM Query Logging

Direct Database Access

Checking Migration State

Gateway Debugging (equabot)

macOS Unified Logs

Process Inspection

WebSocket Debugging

Common Issues

Log Locations

Useful Debug Commands