Troubleshooting

Docker and PostgreSQL

Docker daemon unavailable

If Maven reports that no valid Docker environment was found, start Docker Desktop or the Docker Engine and confirm access:

docker version
docker info

Retry only after both client and server information are available.

Port 5432 already in use

The Compose file intentionally publishes PostgreSQL on the standard host port 5432. Stop the other local PostgreSQL service or container, then rerun docker compose up. Use docker ps to identify containers publishing that port.

Database does not become healthy

Inspect the database logs and the resolved Compose configuration:

docker compose config
docker compose logs db

Check that DB_USERNAME and DB_PASSWORD are consistent for both services.

Tests and migrations

Testcontainers startup failure

Confirm the Docker daemon is reachable, allow the first PostgreSQL image pull to finish, and inspect target/failsafe-reports. Run Maven with stack traces when more context is needed:

mvn -e clean verify

Do not point integration tests at a local PostgreSQL instance; the suite is designed to own its container lifecycle.

Flyway validation failure

Do not edit a migration that may already have been applied. Verify the migration filenames and checksums, then add a new versioned migration for schema changes. For disposable local Compose state, remove and recreate the containers:

docker compose down
docker compose up --build

Generated sources and stale builds

Generated OpenAPI classes are missing

Run the lifecycle phase that owns source generation:

mvn clean compile

Confirm output exists under target/generated-sources/openapi. Do not copy generated classes into src/main/java.

MapStruct implementation is missing

Use JDK 21 and run mvn clean compile. The implementation should appear under target/generated-sources/annotations. If the command succeeds but the IDE still reports an error, reload the Maven project so generated source roots are recognized.

Stale Maven output causes inconsistent behavior

Remove old generated output through the normal clean lifecycle and rerun the full gate:

mvn clean verify

Never repair files under target/ manually; the next clean build will replace them.

Local and published documentation

Local Swagger UI is unavailable

Confirm the application completed startup and use the context-path-aware URL:

http://localhost:8080/api/swagger-ui.html

The public Pages URL does not host Swagger UI. Use the static OpenAPI documentation when the backend is not running locally.

Generated OpenAPI or Maven site is missing locally

Generate contract documentation during verification, then the Maven site:

mvn clean verify
mvn site

Check target/openapi-docs/index.html and target/site/index.html.

GitHub Pages links are not updated

1. Confirm the change was pushed to master.
2. Check the CI/CD workflow and its deploy-pages job.
3. Confirm repository Pages settings use GitHub Actions as the source.
4. Wait for deployment to complete, then refresh the page without the browser cache.

Pull requests verify documentation inputs but do not publish a preview deployment.

Still investigating?

Use the narrowest generated report or log that matches the failure:

• OpenAPI reference
• JaCoCo report
• Maven site
• GitHub Actions runs