Troubleshooting

This guide helps resolve common issues when running or developing Eventara.

Installation Issues

Docker Compose Fails to Start

Symptom: docker compose up fails or services don’t start

Possible Causes and Solutions:

Port conflicts:


# Check if ports are in use
lsof -i :5432  # PostgreSQL
lsof -i :9092  # Kafka
lsof -i :8080  # Spring Boot
lsof -i :5173  # Dashboard
 
# Solution: Stop conflicting services or change ports in docker-compose.yaml

Docker resources:


# Check Docker resources
docker system df
 
# Clean up
docker system prune -a
docker volume prune

Previous containers:


# Stop and remove all containers
docker compose down -v
 
# Restart fresh
docker compose up --build -d

Maven Build Fails

Symptom: ./mvnw clean package fails

Solutions:

Check Java version:
```
java -version  # Should be 21+
```
Clean and rebuild:
```
./mvnw clean
./mvnw package -DskipTests
```

Dependency issues:


# Force update dependencies
./mvnw clean install -U

npm Install Fails

Symptom: npm install in eventara-dashboard fails

Solutions:

Clear cache:


npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Check Node version:
```
node --version  # Should be 18+
```

Runtime Issues

Events Not Being Ingested

Symptom: POST /api/v1/events returns error or events don’t appear

Debugging Steps:

Check API health:


curl http://localhost:8080/api/v1/events/health
# Expected: {"status":"UP","timestamp":"..."}

Check logs:


docker compose logs -f springboot | grep ERROR

Test with minimal payload:


curl -X POST http://localhost:8080/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{"eventType":"test","source":"test"}'

Verify Kafka connection:


docker compose logs kafka | grep -i error

Check database connection:


docker exec postgres14 psql -U postgres -d eventara -c "SELECT COUNT(*) FROM events;"

Kafka Consumer Not Processing Events

Symptom: Events sent to API but not saved to database

Debugging Steps:

Check consumer logs:


docker compose logs springboot | grep EventConsumer

Verify topic exists:


docker exec eventara-kafka kafka-topics \
  --list \
  --bootstrap-server localhost:9092

Check messages in topic:


docker exec eventara-kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic eventara.events.raw \
  --from-beginning \
  --max-messages 10

Check consumer group:


docker exec eventara-kafka kafka-consumer-groups \
  --bootstrap-server localhost:9092 \
  --group eventara-consumer-group \
  --describe

Consumer lag:


# If LAG is increasing, consumer is falling behind
# Check for errors in logs
docker compose logs springboot | grep -A 5 -B 5 "consumer error"

WebSocket Connection Fails

Symptom: Dashboard shows “Connecting…” or connection errors

Debugging Steps:

Check WebSocket endpoint:


curl -I http://localhost:8080/ws/info
# Should return 200 OK

Browser console:
- Open DevTools (F12)
- Check Console for errors
- Check Network tab → WS filter → Look for WebSocket connection

Backend WebSocket logs:


docker compose logs springboot | grep WebSocket

CORS issues:
- Check if dashboard URL is allowed
- Verify @CrossOrigin annotations in controllers
Test with static page:
- Access http://localhost:8080/static/test-websocket.html
- Should establish connection and receive messages

Dashboard Not Loading

Symptom: Dashboard page blank or won’t load

Solutions:

Check dashboard service:
```
docker compose logs dashboard
```
Verify API URL:
- Check eventara-dashboard/.env
- Should be: VITE_API_URL=http://localhost:8080

Rebuild dashboard:


cd eventara-dashboard
npm install
npm run dev

Browser cache:
- Hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
- Clear browser cache

Database Issues

Flyway Migration Fails

Symptom: Application fails to start with Flyway error

Solutions:

Check migration files:


ls -la src/main/resources/db/migration/
# Should be: V1__, V2__, etc. (no gaps)

Reset Flyway schema:


-- Connect to database
docker exec -it postgres14 psql -U postgres -d eventara
 
-- Drop Flyway table
DROP TABLE IF EXISTS flyway_schema_history CASCADE;
 
-- Restart application

Fresh database:


docker compose down -v
docker compose up -d postgres
# Wait for PostgreSQL to be ready
docker compose up -d springboot

Cannot Connect to PostgreSQL

Symptom: Connection refused or authentication failed

Solutions:

Check PostgreSQL is running:
```
docker compose ps postgres
```
Verify credentials:
- Check application.properties
- Should match docker-compose.yaml environment variables

Test connection:


docker exec -it postgres14 psql -U postgres -d eventara

Check logs:


docker compose logs postgres | grep ERROR

Database Query Slow

Symptom: Slow response times or timeouts

Solutions:

Check table size:


SELECT 
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename))
FROM pg_tables
WHERE schemaname = 'public';

Verify indexes:


SELECT * FROM pg_indexes WHERE tablename = 'events';

Query statistics:


SELECT * FROM pg_stat_user_tables WHERE relname = 'events';

Vacuum database:


docker exec postgres14 vacuumdb -U postgres -d eventara -v

Performance Issues

High Memory Usage

Symptom: Application using too much memory or OOM errors

Solutions:

Check JVM heap:


# Add to docker-compose.yaml
environment:
  JAVA_OPTS: "-Xms512m -Xmx2g"

Heap dump analysis:


# Enable heap dump on OOM
JAVA_OPTS: "-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp"
 
# Analyze with jhat or VisualVM

Metrics service memory:
- ComprehensiveMetricsService stores last 1000 latency samples
- Last 24 hours of event timestamps
- Consider reducing retention if memory-constrained

High CPU Usage

Symptom: CPU at 100% or sluggish performance

Solutions:

Profile application:


# Use JProfiler, YourKit, or VisualVM
# Connect to JVM on port 9010 (if enabled)

Check scheduled tasks:


docker compose logs springboot | grep "@Scheduled"

Reduce broadcast frequency:


// In MetricsWebSocketController.java
@Scheduled(fixedRate = 5000)  // Change from 1000ms to 5000ms

Slow Event Ingestion

Symptom: High latency or timeouts on POST requests

Debugging:

Check processing latency:


curl http://localhost:8080/api/v1/metrics | jq '.latencyMetrics.overall'

Kafka producer config:


# Increase batch size for throughput
spring.kafka.producer.properties.batch.size=32768
spring.kafka.producer.properties.linger.ms=20

Database connection pool:


spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5

Check consumer lag:


docker exec eventara-kafka kafka-consumer-groups \
  --bootstrap-server localhost:9092 \
  --group eventara-consumer-group \
  --describe

Alert Rule Issues

Rules Not Triggering

Symptom: Alert rule created but never triggers

Debugging Steps:

Check rule status:


curl http://localhost:8080/api/v1/rules/{id}
# Verify status is "ACTIVE"

Test rule:


curl -X POST http://localhost:8080/api/v1/rules/test/{id}
# Check simulation result

Verify metrics match conditions:


curl http://localhost:8080/api/v1/metrics | jq '.summary'
# Compare with rule threshold

Check DRL compilation:


docker compose logs springboot | grep "DRL"

Rule execution logs:


docker compose logs springboot | grep RuleExecutionService

Rule Compilation Errors

Symptom: Error when creating or testing rule

Solutions:

Validate rule configuration:
- Check all required fields are present
- Verify operator names are correct
- Ensure threshold types match metric types

Test before creating:


curl -X POST http://localhost:8080/api/v1/rules/test \
  -H "Content-Type: application/json" \
  -d @rule-config.json

Check validation errors:


# Response includes validationErrors array
jq '.validationErrors' response.json

Common Error Messages

”Connection refused”

Cause: Service not running or wrong port

Solution:


# Check service status
docker compose ps
 
# Restart service
docker compose restart <service-name>

“Table ‘events’ doesn’t exist”

Cause: Flyway migrations not run

Solution:


# Check Flyway status
docker compose logs springboot | grep Flyway
 
# Restart to trigger migrations
docker compose restart springboot

“Kafka broker not available”

Cause: Kafka not ready or network issue

Solution:


# Wait for Kafka to be ready
docker compose logs kafka | grep "started"
 
# Check health
docker exec eventara-kafka kafka-broker-api-versions \
  --bootstrap-server localhost:9092

“Out of memory error”

Cause: JVM heap too small

Solution:


# In docker-compose.yaml
springboot:
  environment:
    JAVA_OPTS: "-Xmx4g"  # Increase heap size

Debugging Tools

Check All Services Health


#!/bin/bash
echo "PostgreSQL:"
docker exec postgres14 pg_isready
 
echo -e "\nKafka:"
docker exec eventara-kafka kafka-broker-api-versions \
  --bootstrap-server localhost:9092 2>&1 | head -n 1
 
echo -e "\nSpring Boot:"
curl -s http://localhost:8080/api/v1/events/health | jq
 
echo -e "\nDashboard:"
curl -s -o /dev/null -w "%{http_code}" http://localhost:5173

Monitor Real-Time Logs


# All services
docker compose logs -f --tail=100
 
# Specific service with filtering
docker compose logs -f springboot | grep -E "ERROR|WARN"

Kafka Debugging


# List topics
docker exec eventara-kafka kafka-topics \
  --list \
  --bootstrap-server localhost:9092
 
# Consume messages
docker exec eventara-kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic eventara.events.raw \
  --from-beginning
 
# Producer test
docker exec -it eventara-kafka kafka-console-producer \
  --bootstrap-server localhost:9092 \
  --topic eventara.events.raw

Database Debugging


# Connect to PostgreSQL
docker exec -it postgres14 psql -U postgres -d eventara
 
# Useful queries:
-- Count events
SELECT COUNT(*) FROM events;
 
-- Recent events
SELECT event_id, event_type, source, timestamp 
FROM events 
ORDER BY timestamp DESC 
LIMIT 10;
 
-- Events by type
SELECT event_type, COUNT(*) 
FROM events 
GROUP BY event_type 
ORDER BY COUNT(*) DESC;
 
-- Database size
SELECT pg_size_pretty(pg_database_size('eventara'));

Getting Help

If you encounter issues not covered here:

Check logs: Most issues leave traces in logs
GitHub Issues: Search existing issues or create new one
Community: Join discussions on GitHub
Documentation: Review other documentation pages

Reporting Bugs

When reporting issues, include:

Eventara version
Docker/Java/Node versions
Steps to reproduce
Error messages and logs
Expected vs actual behavior
Environment (OS, Docker setup, etc.)