Use this interactive wizard to diagnose and resolve common issues with kombify.
Select the symptom that best describes your issue to get step-by-step resolution guidance.
What are you experiencing?
Installation issues
Problems during initial setup or installation
Connection problems
Agents not connecting, network issues
Deployment failures
Configuration validation or apply errors
Service issues
Services not running or not accessible
Performance problems
Slow operations, high resource usage
Simulation issues
Problems with kombify Simulate
Installation Issues
Docker Compose fails to start
Symptoms
docker compose up fails with errors- Services exit immediately after starting
- Port binding errors
Diagnosis
Check Docker is running
If error: Start Docker daemon or Docker Desktop Check port availability
# Linux/macOS
netstat -tuln | grep -E '5260|5263|5270'
# Windows
netstat -an | findstr "5260 5263 5270"
.envCheck disk space
Need: At least 5GB free space View detailed logs
docker compose logs --tail=50
Common Fixes
Port Conflict
Permission Error
Resource Limits
Edit .env or docker-compose.yml:environment:
- KOMBISTACK_PORT=5261 # Use different port
# Fix Docker socket permissions
sudo chmod 666 /var/run/docker.sock
# Or add user to docker group
sudo usermod -aG docker $USER
Increase Docker resources in Docker Desktop settings:
- Memory: 4GB minimum
- CPU: 2 cores minimum
Binary installation fails
Symptoms
- Install script fails
- Binary not found after install
- Architecture mismatch errors
Diagnosis
Check system architecture
Expected: x86_64 (amd64) or aarch64 (arm64) Check Go version (if building)
Manual Installation
# Download correct binary
ARCH=$(uname -m)
case $ARCH in
x86_64) ARCH="amd64" ;;
aarch64) ARCH="arm64" ;;
esac
curl -L "https://github.com/kombify/kombifyStack/releases/latest/download/kombistack-linux-${ARCH}" -o /usr/local/bin/kombify
chmod +x /usr/local/bin/kombify
Connection Problems
Agent shows 'disconnected' status
Symptoms
- Agent appears in dashboard but shows disconnected
- Heartbeat failures in logs
- Intermittent connectivity
Decision Tree
Step-by-Step Fix
Test network connectivity
# From agent node
ping your-stack-host
nc -zv your-stack-host 5263
Check certificate validity
openssl x509 -in /etc/kombify/agent.crt -text -noout | grep -A2 "Validity"
make certs-agent AGENT=nameVerify time synchronization
timedatectl status
# Should show: NTP synchronized: yes
sudo systemctl enable --now systemd-timesyncd
Check agent logs
journalctl -u kombify-agent -f
Symptoms
connection refused errors- Agent can’t register
- TLS handshake failures
Fixes by Error Type
Connection Refused
TLS Handshake Failed
Certificate Expired
Stack gRPC server not running or wrong port:# Check Stack is running
docker ps | grep stack
# Check port binding
docker port kombify-stack 5263
Certificate mismatch:# On Stack
make certs-init
# On Agent
make certs-agent AGENT=my-node
# Copy new certs to agent
scp data/certs/agent-my-node.* user@agent-host:/etc/kombify/
Regenerate CA and all agent certs:make certs-rotate-ca
make certs-agent AGENT=node1
make certs-agent AGENT=node2
# Redeploy certs to all nodes
Deployment Failures
Common Validation Errors
Unknown Field
Missing Required Field
Type Mismatch
Invalid Service
Error: field "xyz" not allowedCause: Typo or invalid field nameFix: Check StackKit schema for valid fields:kombify schema show base-kit
Error: field "domain" is requiredFix: Add the required field:config:
domain: home.example.com # Add this
Error: expected string, got numberFix: Ensure correct types:# Wrong
port: "8080"
# Correct
port: 8080
Error: service "xyz" not found in StackKitFix: Check available services:kombify services list --stackkit base-kit
Symptoms
- Plan succeeds but apply fails
- Resource creation errors
- Provider errors
Common Fixes
Check provider credentials
For cloud providers, verify credentials:# AWS
aws sts get-caller-identity
# Azure
az account show
Check resource limits
Verify you haven’t hit quota limits in cloud console.
Manual state fix (advanced)
cd data/tofu
tofu state list
tofu state rm problematic.resource
Service Issues
Quick Checks
# Check container status
docker ps -a | grep service-name
# View logs
docker logs service-name --tail=100
# Check resource usage
docker stats --no-stream
Common Causes
| Symptom | Likely Cause | Fix |
|---|
| Exits immediately | Config error | Check logs for specific error |
| OOMKilled | Memory limit | Increase container memory |
| Pending | Volume issue | Check volume mounts exist |
| CrashLoopBackOff | Dependencies | Ensure required services running |
Diagnosis Flow
Verify service is running
docker ps | grep service-name
curl localhost:internal-port/health
Check Traefik routing
Access Traefik dashboard: http://your-host:8080/dashboard/Verify:
- Router exists for your service
- No errors on router
- Correct entrypoint (web/websecure)
Test DNS resolution
nslookup service.yourdomain.com
# Or check /etc/hosts for local domains
Check SSL certificate
openssl s_client -connect service.yourdomain.com:443 -servername service.yourdomain.com
Identification
# Container resource usage
docker stats
# System overview
htop
Mitigation
Set Resource Limits
Scale Horizontally
Optimize Service
In kombination.yaml:services:
my-service:
resources:
memory: 512M
cpu: 0.5
Add more nodes and distribute services.
Check service-specific tuning guides in our docs.
Simulation Issues
Docker Backend
# Check Docker daemon
docker info
# Check Sim logs
docker logs kombify-sim
# Verify Sim can access Docker socket
docker exec kombify-sim docker ps
QEMU Backend
# Check KVM support
lsmod | grep kvm
# Verify QEMU installed
qemu-system-x86_64 --version
# Check permissions
ls -la /dev/kvm
Still Stuck?
If you’ve tried the above steps without success:
Collect Debug Info
Run:This creates a zip file with logs and system info. Get Help
Share the debug bundle in our Discord #support channel.
