Troubleshooting

“ECONNREFUSED” Error in the Vite Console / No Data Loading

The backend server is not running. The Vite client proxies all API requests to localhost:3001. Start the server first:

pnpm --filter @tactihub/server dev

---

Page Not Reachable from Other Devices on the Network

Vite listens on localhost by default. Start with --host:

pnpm --filter @tactihub/client exec vite --host

---

Login Not Working

• The login field accepts both username (admin) and email (admin@tactihub.local)
• Default password is changeme
• On the first login with default credentials, you will be prompted to set new credentials
• The seed user has email already verified
• New users must verify their email first (check SMTP)

---

Email Links Go to the Wrong URL / “Route not found” Error

Email links (verification, password reset) use the APP_URL environment variable. It must point to the frontend:

# Correct — points to frontend
APP_URL=https://planner.tactihub.de

# Wrong — points to API server, shows "Route not found"
APP_URL=http://localhost:3001

---

Verification Emails Not Arriving

Check your SMTP configuration in .env:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@example.com
SMTP_PASS=your-password
SMTP_FROM=noreply@yourdomain.com

Common SMTP Issues

Problem	Solution
Port 465 not working	Set SMTP_SECURE=true (SSL)
Port 587 not working	Leave SMTP_SECURE=false (STARTTLS)
Gmail blocks login	Use an App Password
SMTP_FROM rejected	Some providers require it to match the auth user

Test SMTP Connection

curl --url "smtp://SMTP_HOST:SMTP_PORT" --ssl-reqd \
  --mail-from "SMTP_FROM" --mail-rcpt "your@email.com" \
  --user "SMTP_USER:SMTP_PASS" \
  -T /dev/null

---

db:migrate Fails with “column already exists”

This happens when old migration files in packages/server/drizzle/ conflict after a database reset. When the schema evolved across multiple migrations (e.g. one creates a table, a later one adds a column), regenerating on top of stale files produces duplicates.

Solution: Delete old migration files and regenerate:

rm -rf packages/server/drizzle/*
pnpm db:generate
pnpm db:migrate

Or use the automated script which already includes this step:

bash dev-reset.sh

Tip: dev-reset.sh handles the full reset in one step — nuke DB, clean old migrations, regenerate, migrate, and seed. See Database for details.

---

db:generate Fails with “Cannot find module ’./users.js’”

The drizzle-kit scripts must run through tsx. Check that packages/server/package.json contains:

"db:generate": "tsx ./node_modules/drizzle-kit/bin.cjs generate"

---

db:migrate Fails with url: undefined

The .env file is in the project root, but scripts run from packages/server/. Make sure drizzle.config.ts and connection.ts use:

import { config } from 'dotenv';
config({ path: '../../.env' });

---

docker compose down -v — What Gets Deleted?

Volume	Contents	Deleted?
pgdata	PostgreSQL database (users, games, maps, battle plans, everything)	Yes
redisdata	Redis data (sessions, refresh tokens)	Yes
Code / .env / Uploads	Source code, configuration, uploaded images	No

After down -v:

docker compose up -d && pnpm db:generate && pnpm db:migrate && pnpm db:seed

---

General Tips

• Always check the server logs (pnpm --filter @tactihub/server dev) for detailed error messages
• Make sure Docker is running before starting the server
• For persistent issues: fully reset the database (see Database)