> ## Documentation Index > Fetch the complete documentation index at: https://docs.equa.cc/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://react.dev/learn/react-developer-tools) browser extension to inspect component trees, props, state, and hooks. * **Immutable.js Formatter:** Install [Immutable.js Object Formatter](https://chrome.google.com/webstore/detail/immutablejs-object-format/hgldghadipiblonfkkicmgcbbijnpeog) 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: ```bash theme={null} 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: ```json theme={null} { "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): ```bash theme={null} 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`: ```env theme={null} 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: ```bash theme={null} 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: ```bash theme={null} ./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: ```bash theme={null} launchctl print gui/$UID | grep equabot ``` Check the gateway port: ```bash theme={null} 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 ` | | `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 ```bash theme={null} # 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" ```