Troubleshooting

Common Issues

Solutions to common problems encountered when developing or deploying LAREX.

Common Issues

This guide covers common issues and their solutions when developing or deploying LAREX.

Port Conflicts

Symptoms

  • Services fail to start
  • "Address already in use" errors
  • "Port is occupied" warnings

Solutions

Check what's using a port:

# macOS/Linux
lsof -i :3000
lsof -i :8080
lsof -i :5432
lsof -i :8090

# Windows
netstat -ano | findstr :3000

Kill the process:

# Kill by PID
kill -9 $(lsof -t -i:3000)

# Or stop the conflicting service
docker compose down

Common Ports

PortServiceFix
3000Frontend devtask docker:down or stop local server
8080Backend devtask docker:down or stop local server
5432PostgreSQLStop other PostgreSQL instances
8090Keycloaktask docker:down

Database Connection Issues

Symptoms

  • "Connection refused" errors
  • "Database does not exist" errors
  • Authentication failures

Solutions

Reset database:

# Stop and remove volumes
task docker:down:clean

# Restart infrastructure
task docker:infra

Verify database is running:

# Check PostgreSQL status
docker compose ps postgres

# Test connection
docker compose exec postgres pg_isready -U larex

# Open shell
task db:shell

Check credentials:

# In compose.yaml or .env
POSTGRES_USER=larex
POSTGRES_PASSWORD=larex_dev_pw

Keycloak Authentication Issues

Symptoms

  • Login fails
  • 401 Unauthorized errors
  • Token validation errors

Solutions

Reset Keycloak:

# Stop and remove Keycloak data
docker compose down keycloak
docker volume rm larex_keycloak_data

# Restart
docker compose up -d keycloak

Wait for Keycloak to be ready:

# Check health
curl http://localhost:8090/health/ready

# Wait for ready (max 60s)
until curl -s http://localhost:8090/health/ready | grep -q "UP"; do
  sleep 2
done

Verify realm configuration:

# Check realm is imported
docker compose exec keycloak ls /opt/keycloak/data/import/

Frontend Build Issues

Symptoms

  • Build failures
  • Module not found errors
  • TypeScript errors

Solutions

Clear and reinstall dependencies:

cd frontend

# Remove node_modules and lock file
rm -rf node_modules pnpm-lock.yaml

# Reinstall
pnpm install

# Build
pnpm build

Clear Nuxt cache:

cd frontend
rm -rf .nuxt .output node_modules/.cache
pnpm install
pnpm build

Fix TypeScript errors:

# Run typecheck
pnpm typecheck

# Auto-fix if possible
pnpm lint --fix

Backend Build Issues

Symptoms

  • Gradle build failures
  • Compilation errors
  • Test failures

Solutions

Clean and rebuild:

cd backend

# Clean build
./gradlew clean

# Rebuild
./gradlew build -x test

# Run tests
./gradlew test

Clear Gradle cache:

# Remove Gradle cache
rm -rf ~/.gradle/caches

# Or use Docker volume
docker volume rm larex_gradle_cache

Debug build issues:

# Verbose output
./gradlew build --info

# Stack trace
./gradlew build --stacktrace

Docker Issues

Images Not Building

# Force rebuild
docker compose -f compose.yaml build --no-cache

# Check Docker is running
docker info

# Restart Docker Desktop

Container Crashes

# Check logs
docker compose logs

# Check specific service
docker compose logs app

# Check exit code
docker compose ps -a

Out of Disk Space

# Check disk usage
docker system df

# Clean up
docker system prune -a

# Remove unused volumes
docker volume prune

Memory Issues

# Check container stats
docker stats

# Increase Docker memory limit
# Docker Desktop > Settings > Resources

Hot Reload Not Working

Backend

Check DevTools is enabled:

# In compose.yaml
environment:
  SPRING_DEVTOOLS_RESTART_ENABLED: true
  SPRING_DEVTOOLS_LIVERELOAD_ENABLED: true

Volume mount must be correct:

volumes:
  - ./backend/src:/app/src:cached

Frontend

Check volume mount:

volumes:
  - ./frontend:/app
  - /app/node_modules  # Important!

Clear Vite cache:

cd frontend
rm -rf .nuxt .output node_modules/.vite
pnpm dev

SSL Certificate Issues

LetsEncrypt Not Working

# Check Traefik logs
docker compose logs traefik

# Verify ACME file
docker compose exec traefik cat /letsencrypt/acme.json

# Remove and regenerate
docker compose down
docker volume rm larex_letsencrypt_data
docker compose up -d

Certificate Renewal

# Check certificate expiry
docker compose exec traefik cat /letsencrypt/acme.json | jq '.[].Certificate'

# Force renewal by restarting Traefik
docker compose restart traefik

Performance Issues

Slow Frontend Builds

# Use pnpm instead of npm
cd frontend && pnpm install

# Clear cache
rm -rf .nuxt .output node_modules/.cache

Slow Backend Tests

# Use in-memory database for tests
# Configure in application-test.yaml

# Parallel execution
./gradlew test --parallel

High Memory Usage

# Limit Docker memory
# Docker Desktop > Settings > Resources

# Check container memory
docker stats

Debug Mode

Backend Debug

Start with debug port:

cd backend
./gradlew bootRun -Pdebug

Attach debugger in IDE:

  • Host: localhost
  • Port: 5005

Frontend Debug

# With verbose logging
pnpm dev --debug

# Vue DevTools enabled
pnpm dev

Enable Debug Logging

# application.yaml
logging:
  level:
    root: DEBUG
    de.uniwue.zpd.dachs.larex: DEBUG

Getting Help

If your issue is not listed here:

  1. Check logs for detailed error messages
  2. Search existing GitHub issues
  3. Run health checks:
# Backend health
curl http://localhost:8080/actuator/health

# Frontend health
curl http://localhost:3000/api/health/backend

# Keycloak health
curl http://localhost:8090/health
  1. Collect information for bug reports:
# Docker status
docker compose ps

# Recent logs
docker compose logs --tail=100

# Version info
task ver

Keycloak Setup for Institutions

Configure Keycloak for institutional authentication with LDAP user federation.

Workspace and Library

Manage workspaces and projects in the LAREX library.

Copyright © 2026