home/Projects/kompose/docs/content/3.guide/troubleshooting.md

title, description

title	description
Troubleshooting	Common issues and solutions

Common Issues

:icon{name="lucide:ban"} 404 Error from Traefik

Problem: Websites return 404 even though containers are running

Solution:

# Check Traefik logs
docker logs proxy_app

# Verify network configuration
docker network inspect kompose

# Restart proxy and affected stacks
./kompose.sh proxy down && ./kompose.sh proxy up -d
./kompose.sh blog restart

Debug:

# Check Traefik dashboard
http://your-server:8080

# Verify container labels
docker inspect blog_app | grep traefik

:icon{name="lucide:hard-drive"} Database Import Fails

Problem: db:import command fails

Common causes:

1. Active connections - Solved automatically (kompose terminates connections)
2. Missing dump file - Check file path
3. Insufficient permissions - Check DB_USER permissions
4. Wrong database - Verify DB_NAME in stack .env

Solution:

# Check database connectivity
docker exec data_postgres psql -U $DB_USER -l

# Verify dump file exists
ls -lh news/*.sql

# Check logs for detailed error
./kompose.sh news db:import 2>&1 | tee import.log

:icon{name="lucide:plug"} Container Won't Connect to Network

Problem: Container fails to join kompose network

Solution:

# Recreate network
docker network rm kompose
docker network create kompose

# Restart all stacks
./kompose.sh "*" down
./kompose.sh "*" up -d

:icon{name="lucide:git-branch"} Hooks Not Executing

Problem: Custom hooks aren't running

Checklist:

• hooks.sh file exists in stack directory
• hooks.sh is executable: chmod +x <stack>/hooks.sh
• Function names match: hook_pre_db_export, etc.
• Functions return 0 (success) or 1 (failure)

Test:

# Dry-run shows hook execution
./kompose.sh sexy db:export --dry-run

# Check if hooks.sh exists
./kompose.sh --list | grep hooks

Debug Mode

Enable verbose logging:

# View Traefik debug logs
docker logs -f proxy_app

# Check environment variables
./kompose.sh news ps
docker exec news_backend env

# Inspect running containers
docker ps -a
docker inspect <container_name>

Getting Help

1. Check logs: ./kompose.sh <stack> logs
2. Use dry-run: ./kompose.sh --dry-run <pattern> <command>
3. List stacks: ./kompose.sh --list
4. Read help: ./kompose.sh --help
5. Open an issue: GitHub Issues