FAQ — dev environment & daily problems

Tripped on something for 10+ minutes? Once it's solved, add it here (question → answer → command). This page is the team's memory — editing it is always allowed, no review needed.

API

The API won't start — "port 5432 already in use" Something else runs PostgreSQL on your machine. Either stop it, or change the mapped port in docker-compose.yml (e.g. "5433:5432") and set DB_URL=jdbc:postgresql://localhost:5433/trizagenda. Check what's running: docker compose ps · sudo lsof -i :5432

Flyway "checksum mismatch" / "migration failed" on startup You (or a pull) changed an already-applied migration — never edit a migration that ran. Dev-only reset (wipes local data): docker compose down -v && docker compose up -d, restart the API. If you need a schema change: new V<n>__description.sql, and announce "taking V" in the channel first.

Where is the password-reset email? There is no real email in dev — the token prints in the API console (look for the PASSWORD RESET (dev email stub) block). Token is single-use and expires in 1 hour.

Login suddenly returns 429 Rate limit: 10 login attempts/min per IP (5/min for reset requests). Wait a minute. If you're writing a script/test that logs in repeatedly, log in once and reuse the token.

./mvnw: Permission denied The zip stripped the executable bit: chmod +x mvnw (or use your own mvn).

What are the dev credentials? admin@triztech.dz / Admin123! — created by the dev-profile seeder (--spring.profiles.active=dev). No seeder = no users = every login 401.

Web

Login works but every other call returns 401 in a loop Check that VITE_API_BASE_URL points at the real API (http://localhost:8080/api/v1) for auth — the Prism mock can't issue real tokens. Also confirm the API's CORS_ORIGINS includes your dev origin (http://localhost:5173 is the default) — without it the refresh cookie never arrives.

How do I run the mock? npm run mock → spec-faithful fake API on http://localhost:4010. It returns example data from the spec — don't debug "wrong values" on the mock; only shapes are meaningful there.

Where do server-side field errors show up? 400 VALIDATION_FAILED responses carry error.details[] with field + message — map them onto the matching inputs (see the conventions in ARCHITECTURE.md §4).

Mobile

The app can't reach the API from the Android emulator localhost inside the emulator is the emulator itself. Use 10.0.2.2: flutter run --dart-define=API_BASE_URL=http://10.0.2.2:8080/api/v1 Physical device on the same Wi-Fi: your machine's LAN IP instead (and both on the same network).

flutter analyze complains after I pulled Run flutter pub get first — dependency changes need a fresh resolve. Analyzer must be clean before every PR (agreement).

Cross-cutting

"It works on the mock but fails on the real API" Expected — that's exactly what integration checkpoints exist to catch. File a kind/bug issue with the failing request, expected vs actual, and the X-Request-Id response header value (it's on every API response — it finds the exact server log line).

Which name is right — service or department? meeting or appointment? Both, in different worlds. API/spec/UI say services, meetings, reservations; the DB says departments, appointments, resource_bookings. Same for roles: API is French (RESPONSABLE…), DB is English (MANAGER…). The API's mapping layer is the only place both exist — details in trizagenda-api/ARCHITECTURE.md.

I think the spec is wrong / missing something Don't code around it. Say it in the channel → weekly sync decides → spec version bumps → copies in web/mobile repos get re-copied. Spec changes are team decisions (see the working agreements §1).

I accidentally committed a secret Tell the PM immediately — no blame, speed matters. We rotate the secret and scrub history together.