Skip to main content
This guide covers common issues you might encounter when running the KrakenD Playground and how to resolve them.

​
Services Not Starting

​
Checking Service Status

View the status of all services: 
docker compose ps
Healthy services show Up status. Services that failed to start show Exit or Restarting.

​
Viewing Service Logs

Check logs for a specific service: 
# View all logs
docker compose logs

# View specific service logs
docker compose logs krakend_ce
docker compose logs influxdb
docker compose logs elasticsearch

# Follow logs in real-time
docker compose logs -f krakend_ce

​
View Logstash Logs

The Makefile includes a shortcut for viewing Logstash logs: 
make logs
This runs docker compose logs -f logstash.

​
Service Dependencies

If KrakenD fails to start, check its dependencies:
  • fake_api must be running (KrakenD backends)
  • jaeger must be running (tracing exporter)
If JWT revoker fails:
  • krakend_ce must be running first

​
Port Conflicts

​
Identifying Port Conflicts

If you see errors like bind: address already in use, another service is using the same port. Common conflicting ports:
  • 8080 - KrakenD (may conflict with other web services)
  • 3000 - Demo web app (may conflict with other Node.js apps)
  • 5601 - Kibana
  • 9200 - Elasticsearch (mapped to 19200 to avoid conflicts)

​
Finding What’s Using a Port

On Linux/macOS: 
sudo lsof -i :8080
On Windows: 
netstat -ano | findstr :8080

​
Resolving Port Conflicts

Option 1: Stop the conflicting service Option 2: Change the host port in docker-compose.yml For example, to change KrakenD from port 8080 to 8081: 
krakend_ce:
  ports:
    - "8081:8080"  # Changed from 8080:8080
Then restart: 
make restart

​
Configuration Errors

​
Invalid KrakenD Configuration

If KrakenD fails to start due to configuration errors, check the logs: 
docker compose logs krakend_ce
Look for JSON syntax errors or configuration validation failures.

​
Validating KrakenD Configuration

Manually validate your config/krakend/krakend.json: 
docker run --rm -v "$PWD/config/krakend:/etc/krakend" \
  krakend check -c /etc/krakend/krakend.json
This will show any configuration errors without starting the service.

​
Validating Flexible Configuration

If you’re using the flexible configuration template (krakend-flexible-config.tmpl): 
make compile-flexible-config
This compiles the template and validates the output. The compiled configuration is saved to config/krakend/krakend-flexible-config.compiled.json. The command runs: 
docker run \
  -v $(PWD)/config/krakend/:/etc/krakend/ \
  -e FC_ENABLE=1 \
  -e FC_SETTINGS=/etc/krakend/settings/dev \
  -e FC_PARTIALS=/etc/krakend/partials \
  -e FC_TEMPLATES=/etc/krakend/templates \
  -e FC_OUT=/etc/krakend/krakend-flexible-config.compiled.json \
  krakend \
  check -c krakend-flexible-config.tmpl

​
Configuration Not Reloading

The KrakenD playground uses the watch image variant that automatically reloads configuration changes. If changes aren’t being picked up:
  1. Verify you’re editing the correct file: config/krakend/krakend.json
  2. Check the file is valid JSON (use a JSON validator)
  3. Watch the KrakenD logs for reload events: docker compose logs -f krakend_ce
  4. If still not working, manually restart: make restart

​
Service Management Commands

​
Restart All Services

Restart all services without removing volumes: 
make restart
This runs docker compose restart.

​
Restart Single Service

Restart a specific service: 
docker compose restart krakend_ce

​
Completely Reset Environment

Stop all services and remove volumes: 
make stop
This runs docker compose down --volumes, which:
  • Stops all containers
  • Removes all containers
  • Removes all volumes (clears all data)
Then start fresh: 
make start

​
Rebuild Services

If you’ve modified Dockerfiles or need to rebuild images: 
make start
This runs docker compose build web && docker compose up -d, which rebuilds the web app and starts all services. To rebuild everything: 
docker compose build
docker compose up -d

​
Common Service Issues

​
Elasticsearch Won’t Start

Symptom: Elasticsearch exits immediately or shows OOM errors. Cause: Insufficient memory or vm.max_map_count too low. Solution:
  1. Increase Docker memory: Ensure Docker has at least 4GB RAM allocated
  2. Increase vm.max_map_count (Linux/macOS): 
    sudo sysctl -w vm.max_map_count=262144
  3. Check Elasticsearch logs: 
    docker compose logs elasticsearch

​
Grafana Shows “Origin Not Allowed”

Cause: CORS configuration issue. Solution: Access Grafana at the correct URL: http://localhost:4000

​
RabbitMQ Management UI Not Accessible

Cause: RabbitMQ may still be initializing. Solution:
  1. Wait 30 seconds after starting
  2. Access http://localhost:15672
  3. Default credentials: guest / guest

​
Keycloak Realm Not Found

Symptom: Keycloak starts but the krakend realm is missing. Cause: Realm import failed or volume mount incorrect. Solution:
  1. Check volume mount: ./config/keycloak/realms:/opt/keycloak/data/import
  2. Verify import files exist: ls config/keycloak/realms/
  3. Check Keycloak logs: docker compose logs keycloak
  4. Ensure the command includes: --import-realm

​
JWT Revoker Constantly Restarting

Symptom: jwt_revoke service shows Restarting status. Cause: Cannot connect to KrakenD. Solution:
  1. Ensure KrakenD is running: docker compose ps krakend_ce
  2. Check JWT revoker logs: docker compose logs jwt_revoke
  3. Verify KrakenD is accessible from containers: docker compose exec jwt_revoke wget -O- http://krakend_ce:8080/__health

​
Network Issues

​
Cannot Access Services from Host

Symptom: curl http://localhost:8080 fails. Cause: Services not exposing ports correctly. Solution:
  1. Check services are running: docker compose ps
  2. Verify port mappings in docker-compose.yml
  3. Check firewall/security software isn’t blocking ports
  4. On Windows/macOS, ensure Docker Desktop is running

​
Services Cannot Communicate

Symptom: Backend connection errors in KrakenD logs. Cause: Docker network issue. Solution:
  1. Services should use service names as hostnames (e.g., http://fake_api:80)
  2. Restart Docker Compose network: 
    docker compose down
docker compose up -d

​
Performance Issues

​
Services Running Slowly

Cause: Insufficient resources allocated to Docker. Solution:
  1. Check Docker resource limits: Docker Desktop > Settings > Resources
  2. Recommended minimums:
    • Memory: 4GB
    • CPU: 2 cores
    • Swap: 1GB
  3. Disable unused services to reduce resource usage

​
High CPU Usage

Cause: Elasticsearch or Logstash may be indexing heavily. Solution:
  1. Reduce logging verbosity in KrakenD
  2. Increase Elasticsearch heap size if you have more RAM: 
    environment:
  - "ES_JAVA_OPTS=-Xms2048m -Xmx2048m"

​
Data and Volume Issues

​
Persistent Data Not Saving

Cause: No named volumes defined for persistence. Solution: The playground is designed for development and doesn’t persist data by default. Use make stop only when you want to clear all data.

​
Disk Space Issues

Symptom: Services fail with “no space left on device”. Solution:
  1. Clean up Docker resources: 
    docker system prune -a --volumes
  2. Remove old playground volumes: 
    make stop

​
Getting Help

​
Enable Debug Logging

Edit config/krakend/krakend.json to enable debug mode: 
{
  "version": 3,
  "extra_config": {
    "telemetry/logging": {
      "level": "DEBUG"
    }
  }
}
Restart KrakenD and check logs: 
docker compose restart krakend_ce
docker compose logs -f krakend_ce

​
Capture Full Diagnostic Information

Collect comprehensive diagnostic data: 
# Service status
docker compose ps > diagnostic.txt

# All service logs
docker compose logs >> diagnostic.txt

# Docker info
docker info >> diagnostic.txt

# Docker version
docker version >> diagnostic.txt

​
Community Support

If you’re still stuck: Include your diagnostic information and describe:
  • What you were trying to do
  • What you expected to happen
  • What actually happened
  • Relevant log excerpts

Build docs developers (and LLMs) love

Get started for freeTalk to us