Skip to main content
This guide helps you diagnose and resolve common issues with kombify TechStack.

​
Quick diagnostics

Run a quick health check: 
# API health
curl http://localhost:5260/api/v1/health

# Detailed server info
curl http://localhost:5260/api/v1/info

​
Common issues

Symptoms: Connection refused, timeoutSolutions:
  1. Check if Stack is running: 
    docker ps | grep kombistack
# or
systemctl status kombistack
  2. Verify port is listening: 
    netstat -tlnp | grep 5260
  3. Check firewall rules: 
    # Linux
sudo ufw status
# or
sudo iptables -L -n | grep 5260
  4. Check Docker logs: 
    docker logs kombistack
Symptoms: Worker shows as unreachable or pendingSolutions:
  1. Verify agent is running on the node: 
    systemctl status kombify-agent
  2. Check agent logs: 
    journalctl -u kombify-agent -f
  3. Test connectivity from agent to Stack: 
    curl -v https://stack-server:5263
  4. Verify certificates: 
    openssl s_client -connect stack-server:5263
  5. Check if worker needs approval: 
    curl http://localhost:5260/api/v1/workers?status=pending
Symptoms: “Validation failed” errorSolutions:
  1. Check your kombination.yaml syntax: 
    # Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('kombination.yaml'))"
  2. Get detailed validation errors: 
    curl -X POST http://localhost:5260/api/v1/unifier/validate \
  -H "Content-Type: application/yaml" \
  --data-binary @kombination.yaml
  3. Common validation errors:
    • Missing required fields
    • Invalid service names
    • Unsupported StackKit
    • Resource constraints violated
Symptoms: “certificate verify failed”, “unknown CA”Solutions:
  1. For mTLS agent connections, ensure CA is correct: 
    # On Stack server
ls -la /data/certs/

# Verify CA matches
openssl x509 -in /data/certs/ca.crt -text -noout
  2. Regenerate certificates: 
    make certs-init
make certs-agent AGENT=node-1
  3. For Let’s Encrypt issues:
Symptoms: “database locked”, corruption warningsSolutions:
  1. Check database file permissions: 
    ls -la /data/kombistack.db*
  2. For “database locked”: 
    # Check for stuck processes
fuser /data/kombistack.db

# If safe, restart Stack
docker restart kombistack
  3. Restore from backup: 
    # List backups
ls /data/backups/

# Restore
cp /data/backups/kombistack-2026-02-01.db /data/kombistack.db
Symptoms: Drift alerts for unchanged resourcesSolutions:
  1. Check drift details: 
    curl http://localhost:5260/api/v1/stacks/{stack-id}/drift
  2. Common causes:
    • Manual changes on nodes (not via Stack)
    • Container restarts changing IPs
    • Time-based values in configs
  3. Resolve drift: 
    # Apply Stack state to nodes
curl -X POST http://localhost:5260/api/v1/stacks/{stack-id}/drift/resolve

# Or ignore specific drift
curl -X POST http://localhost:5260/api/v1/stacks/{stack-id}/drift/ignore \
  -d '{"resources": ["traefik.config"]}'
Symptoms: Deployment succeeds but services unhealthySolutions:
  1. Check service logs on node: 
    ssh node-1 "docker logs traefik"
  2. Verify resources available: 
    ssh node-1 "docker stats --no-stream"
ssh node-1 "df -h"
  3. Check network connectivity: 
    ssh node-1 "docker network ls"
ssh node-1 "docker network inspect kombify"
  4. Verify port bindings: 
    ssh node-1 "netstat -tlnp | grep -E '80|443'"

​
Log analysis

​
Enable debug logging

# Via environment variable
KOMBISTACK_LOG_LEVEL=debug docker run ...

# Or via API at runtime
curl -X PATCH http://localhost:5260/api/v1/settings \
  -d '{"log_level": "debug"}'

​
Log locations

ComponentLocation
Stack APIdocker logs kombistack or stdout
Agent/var/log/kombify-agent.log or journald
OpenTofu/data/tofu/logs/
PocketBaseEmbedded in Stack logs

​
Log filtering

# Filter for errors only
docker logs kombistack 2>&1 | jq 'select(.level=="ERROR")'

# Filter by component
docker logs kombistack 2>&1 | jq 'select(.component=="unifier")'

# Filter by job ID
docker logs kombistack 2>&1 | jq 'select(.job_id=="job_abc123")'

​
Diagnostic commands

​
Get system info

curl http://localhost:5260/api/v1/info | jq

​
Export debug bundle

Collect all diagnostic information: 
curl -o debug-bundle.tar.gz \
  http://localhost:5260/api/v1/debug/bundle
This includes:
  • Logs (last 24h)
  • Configuration (sanitized)
  • Worker status
  • Recent job history
  • System metrics

​
Check connectivity matrix

curl http://localhost:5260/api/v1/workers/connectivity

​
Recovery procedures

​
Reset stuck job

# Cancel stuck job
curl -X POST http://localhost:5260/api/v1/jobs/{job-id}/cancel

# Force cleanup
curl -X POST http://localhost:5260/api/v1/jobs/{job-id}/cleanup

​
Rebuild worker connection

# On Stack server
curl -X DELETE http://localhost:5260/api/v1/workers/{worker-id}

# On node - restart agent
systemctl restart kombify-agent

​
Factory reset (caution!)

This removes all data. Only use as last resort.
# Stop Stack
docker stop kombistack

# Backup data first
cp -r /data /data.backup.$(date +%Y%m%d)

# Remove database
rm /data/kombistack.db*

# Restart Stack
docker start kombistack

​
Getting help

If you’re still stuck:
  1. Search docs: Use the search bar above
  2. Community Discord: discord.gg/kombify
  3. GitHub Issues: github.com/kombify/stack/issues
When reporting issues, include:
  • Stack version (curl http://localhost:5260/api/v1/info)
  • Error messages (full log output)
  • Steps to reproduce
  • Your kombination.yaml (sanitized)