> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Debugging

Tips for debugging issues in local development.

## Viewing logs

When running `npm run dev`, logs from all services appear in your terminal. For structured logging, metrics, and distributed tracing, see [Observability](/docs/features/observability.md).

To view Docker container logs separately:

```bash
# All container logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# Specific service
docker compose logs auth-service

# Last 100 lines
docker compose logs --tail 100
```

## Hot reload

Services automatically restart when you save changes. The generated `docker-compose.yml` mounts your source code:

```yaml
services:
  auth-service:
    volumes:
      - ./apps/auth-service/src:/app/src
```

If changes aren't picked up:

1. Check the file is inside `src/`
2. Restart: `Ctrl+C` then `npm run dev`

## Database access

### [pgAdmin](https://www.pgadmin.org/) (built-in)

tsdevstack automatically generates pgAdmin with all your databases pre-configured:

```
http://localhost:5050
Login: admin@localhost.com / admin
```

All service databases appear in the sidebar. Database credentials are pre-loaded via pgpass, so clicking a database connects automatically - no password prompts.

### [Prisma Studio](https://www.prisma.io/studio)

Each service with a database has a generated `.env` file with `DATABASE_URL`. Run Prisma Studio for a service:

```bash
cd apps/auth-service && npx prisma studio
```

Opens at `http://localhost:5555` with a visual interface for browsing and editing data. Run from the service directory to use its `.env` file.

### CLI access

Each service has its own database container. Connect via Docker:

```bash
# Connect to auth database
docker compose exec auth-db psql -U $AUTH_DB_USER -d auth-service

# Connect to offers database
docker compose exec offers-db psql -U $OFFERS_DB_USER -d offers-service
```

Or directly (if you have psql installed):

```bash
# User and password are in .secrets.local.json (AUTH_DB_USER / AUTH_DB_PASSWORD)
psql postgresql://<user>:<password>@localhost:5432/auth-service
```

### Other GUI tools

You can also use DBeaver, TablePlus, or similar tools:

| Database  | Host      | Port | Database       | User                                         | Password                                         |
| --------- | --------- | ---- | -------------- | -------------------------------------------- | ------------------------------------------------ |
| auth-db   | localhost | 5432 | auth-service   | See `.secrets.local.json` (`AUTH_DB_USER`)   | See `.secrets.local.json` (`AUTH_DB_PASSWORD`)   |
| offers-db | localhost | 5433 | offers-service | See `.secrets.local.json` (`OFFERS_DB_USER`) | See `.secrets.local.json` (`OFFERS_DB_PASSWORD`) |

Ports are auto-assigned starting from 5432. Check `docker-compose.yml` for actual port mappings. Passwords are generated by the framework and stored in `.secrets.local.json`.

## Common issues

### Port already in use

```bash
# Find what's using the port
lsof -i :8000

# Kill it
kill -9 <PID>
```

### Container won't start

Check logs for the specific service:

```bash
docker compose logs auth-service
```

Common causes: missing env vars, syntax errors, database not ready.

### Kong returns 502

The gateway can't reach the backend. Check the service is running:

```bash
docker compose ps
```

If services are unhealthy, regenerate configs and restart:

```bash
npx tsdevstack sync
docker compose down && npm run dev
```

### TypeScript errors

Check compilation:

```bash
npm run build -w auth-service
```

## Debug checklist

1. Check logs: `docker compose logs -f`
2. Verify containers: `docker compose ps`
3. Regenerate configs: `npx tsdevstack sync`
4. Restart: `docker compose down && npm run dev`
5. Rebuild: `docker compose build --no-cache`
