Vai al contenuto

Troubleshooting

Problemi ricorrenti e soluzioni note. Se non trovi il tuo caso, apri una issue.

Build

./mvnw not found o permission denied

Su Linux/macOS rendi eseguibile il wrapper: 

chmod +x mvnw
Su Windows usa mvnw.cmd.

Source option 21 is no longer supported

Stai usando un JDK < 21. Controlla con java -version e installa JDK 21.

Test integration falliscono con Could not find a valid Docker environment

Testcontainers richiede Docker in esecuzione. Verifica docker info; su macOS/Windows avvia Docker Desktop.

Database / Flyway

Validate failed: Migrations have failed validation

Una migration esistente è stata modificata dopo essere stata applicata. Soluzione:

  1. In dev: cancella e ricrea il DB locale (docker compose down -v && docker compose up -d postgres).
  2. In prod: scrivi una nuova migration V2__fix_xxx.sql. Non modificare mai una migration già applicata in produzione.
HHH000179: Unable to construct current date o problemi timezone

Configurato in application.yml: 

spring.jpa.properties.hibernate.jdbc.time_zone: UTC

Runtime

Whitelabel Error Page su tutti gli endpoint

Verifica che il controller sia nel package scansionato (dev.federicocalo.sbfs).

Porta 8080 già in uso

Cambia porta: 

SERVER_PORT=8081 ./mvnw spring-boot:run

Errore application/problem+json non riconosciuto dal client

È RFC 7807, parte dello standard HTTP. La maggior parte dei client lo accetta come JSON. Se il tuo client non lo fa, parserizzalo come JSON normale — il body è valido JSON.

Docker

docker compose up --build lento al primo run

Normale: Maven scarica le dipendenze nello stage build. I run successivi usano la cache.

App non si collega al Postgres in compose

Verifica:

  1. Il servizio postgres deve essere service_healthy prima dell'app (depends_on ok).
  2. L'URL nel compose è jdbc:postgresql://postgres:5432/sbfs (hostname = nome servizio, NON localhost).

Documentazione

mkdocs serve non trova un plugin

Installa le dipendenze in un venv: 

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-docs.txt
mkdocs serve

mkdocs build --strict fallisce per link rotti

Usa link relativi corretti (es. [step-02](step-02.md) se sei in steps/).

CI

Coverage gate fallisce nel build

JaCoCo enforce 70%. Aggiungi test al codice non coperto o abbassa temporaneamente in pom.xml (jacoco.minimum.coverage).

GitHub Pages non si aggiorna

Verifica:

  1. Settings → Pages → Source impostato su GitHub Actions.
  2. Il workflow docs.yml è verde.
  3. Cache CDN: forza refresh con Ctrl+Shift+R.