Skip to main content
This guide covers common issues you may encounter when using kombify Simulate and how to resolve them.

​
Quick diagnostics

Run these commands first to gather diagnostic information: 
# Check Sim health
curl http://localhost:5270/health

# Check Docker status
docker ps -a | grep kombisim

# View Sim logs
docker logs kombisim-api --tail 100

# Check resource usage
docker stats --no-stream

​
Common issues

Symptoms:
  • Node stays in “creating” state
  • Error: “Cannot start container”
Possible causes:
  1. Docker socket not mounted Verify the socket is mounted: 
    docker inspect kombisim-api | grep -A5 Mounts
    Fix: Ensure /var/run/docker.sock is mounted in your docker-compose.yml
  2. Insufficient resources Check available resources: 
    docker system df
docker system info | grep -E "CPUs|Memory"
    Fix: Free up disk space or increase Docker resource limits
  3. Port conflict Check if SSH ports are in use: 
    netstat -tuln | grep -E "3000[0-9]"
    Fix: Stop conflicting services or change SSH port range
Resolution steps:
# Restart Sim
docker compose restart kombisim-api

# If that fails, recreate
docker compose down
docker compose up -d
Symptoms:
  • Connection refused when SSH-ing to node
  • Node shows as “running” but can’t connect
Check 1: Is the node actually running?
docker ps | grep <node-id>
Check 2: Is SSH server running inside the container?
docker exec <container-id> pgrep sshd
If sshd isn’t running:
docker exec <container-id> /usr/sbin/sshd
Check 3: Correct port? Get the correct SSH port from the API:
curl http://localhost:5270/api/v1/nodes/<node-id>/ssh
Check 4: Firewall?
# Windows
netsh advfirewall firewall show rule name=all | findstr "3000"

# Linux
sudo iptables -L -n | grep 3000
Fix: Reset node
curl -X POST http://localhost:5270/api/v1/nodes/<node-id>/stop
curl -X POST http://localhost:5270/api/v1/nodes/<node-id>/start
Symptoms:
  • API calls fail with 500 status
  • Dashboard shows errors
Check logs:
docker logs kombisim-api --tail 200 2>&1 | grep -i error
Common causes:
  1. Database corruption 
    # Check database file
ls -la data/kombisim.db

# If corrupted, reset (loses all data)
rm data/kombisim.db
docker compose restart kombisim-api
  2. Docker API issues 
    # Test Docker API access
docker exec kombisim-api curl --unix-socket /var/run/docker.sock http://localhost/version
  3. Memory exhaustion 
    docker stats kombisim-api --no-stream
# Check Memory % - if near 100%, increase limits
Symptoms:
  • Simulations empty after Sim restart
  • Nodes gone but containers still exist
Cause: Database wasn’t persisted properly.Fix: Ensure data volume is configured:
# docker-compose.yml
services:
  kombisim-api:
    volumes:
      - ./data:/app/data  # Persist database
      - /var/run/docker.sock:/var/run/docker.sock
Recovery (if containers exist):
# List orphan containers
docker ps -a | grep kombisim_node

# Clean up
docker rm -f $(docker ps -aq -f name=kombisim_node)
Symptoms:
  • Host system slow
  • Docker using excessive resources
Identify resource-heavy nodes:
docker stats --no-stream
Reduce resource usage:
  1. Stop unused simulations: 
    curl -X POST http://localhost:5270/api/v1/simulations/<id>/stop
  2. Reduce node resources in simulation config: 
    {
  "resources": {
    "vcpus": 1,
    "memory_mb": 512
  }
}
  3. Use minimal template: 
    curl -X POST http://localhost:5270/api/v1/templates/single-local/apply
Symptoms:
  • POST /nodes/{id}/latency succeeds but no effect
  • Ping times unchanged
Cause: The container doesn’t have NET_ADMIN capability.Fix: Recreate simulation with proper config:
{
  "nodes": [{
    "name": "test-node",
    "capabilities": ["NET_ADMIN"]
  }]
}
Verify tc rules inside container:
docker exec <container-id> tc qdisc show
Symptoms:
  • Blank page or spinner
  • Console errors
Check frontend service:
curl http://localhost:5271/
If using Docker Compose with separate frontend:
docker logs kombisim-ui --tail 100
Common fixes:
  1. Clear browser cache
  2. Check CORS settings if API is on different domain
  3. Verify API URL in frontend config
Reset frontend:
docker compose restart kombisim-ui

​
Engine-specific issues

​
Docker-specific issues

Permission denied on socket:
# Check socket permissions
ls -la /var/run/docker.sock

# Fix: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
Out of disk space:
# Clean up Docker
docker system prune -a --volumes
Network conflicts:
# List networks
docker network ls | grep kombisim

# Remove conflicting network
docker network rm <network-id>

​
Log analysis

​
Log levels

Set log level in environment: 
KOMBISIM_LOG_LEVEL=debug docker compose up
LevelDescription
errorErrors only
warnWarnings and errors
infoStandard logging (default)
debugDetailed debugging

​
Key log patterns

# Find all errors
docker logs kombisim-api 2>&1 | grep -i error

# Find node lifecycle events
docker logs kombisim-api 2>&1 | grep -E "node|container"

# Find API requests
docker logs kombisim-api 2>&1 | grep -E "POST|GET|DELETE"

​
Getting help

If you can’t resolve your issue:
  1. Gather diagnostics: 
    docker logs kombisim-api > sim-logs.txt 2>&1
curl http://localhost:5270/health > health.json
docker ps -a > containers.txt
  2. Check GitHub issues: github.com/kombify/sim/issues
  3. Ask on Discord: discord.gg/kombify — #sim-support channel
  4. Report a bug: Include logs, health output, and steps to reproduce.