Troubleshooting
Common issues and solutions for DevEnv Pro
Troubleshooting
Common issues and solutions for DevEnv Pro.
Quick Diagnostics
# Check all services
docker compose ps
# Check service health
docker compose ps
# View logs
docker compose logs -f
# Restart all services
docker compose restartIssues by Service
Guacamole Issues
Port 8081 Already in Use
Symptom: Bind for 0.0.0.0:8081 failed: port is already allocated
Solution:
# Find what's using the port
sudo lsof -i :8081
# Stop conflicting service
sudo systemctl stop <service>
# Or change port in docker-compose.yamlConnection Failed
Symptom: "Connection failed" when trying to connect
Solutions:
-
Check devenv is healthy:
docker compose ps devenv -
Check xrdp is running:
docker exec mks-devenv-full supervisorctl status xrdp -
Test from inside the network:
docker exec mks-guacamole ping devenv
Blank Screen
Symptom: Connection succeeds but shows blank screen
Solutions:
-
Check Xvfb is running:
docker exec mks-devenv-full supervisorctl status xvfb -
Check Xfce4 is running:
docker exec mks-devenv-full supervisorctl status xfce4 -
Restart desktop services:
docker exec mks-devenv-full supervisorctl restart desktop:*
Database Not Initialized
Symptom: "Database schema not found" errors
Solution:
cd guacamole
./init.shdevenv-full Issues
Container Won't Start
Symptom: Container exits immediately
Solution:
# Check logs
docker compose logs devenv
# Check resource usage
docker stats
# Verify Docker daemon is running
docker infoVS Code Extensions Not Loading
Symptom: Extensions fail to install or load
Solution:
# Reinstall extensions
docker exec mks-devenv-full code-server --list-extensions
docker exec mks-devenv-full code-server --install-extension <extension-id>SSH Connection Refused
Symptom: "Connection refused" on port 2222
Solutions:
-
Check SSH service is running:
docker exec mks-devenv-full supervisorctl status sshd -
Verify SSH key is configured
-
Check firewall allows port 2222
Code-Server Not Accessible
Symptom: Can't access http://localhost:8443
Solutions:
-
Check Code-Server is running:
docker exec mks-devenv-full supervisorctl status codeserver -
Verify password in
.env -
Check health:
curl -f http://localhost:8443/healthz
General Issues
Out of Memory
Symptom: Containers killed with OOM error
Solution:
# Check memory usage
docker stats
# Increase Docker memory limit (Docker Desktop settings)
# Or add memory limit to docker-compose.yaml:
deploy:
resources:
limits:
memory: 4GDisk Space Full
Symptom: Cannot write to filesystem
Solution:
# Check disk usage
df -h
# Clean up Docker
docker system prune -a
# Clean up old volumes
docker volume ls
docker volume rm <volume-name>Timezone Issues
Symptom: Wrong time in container
Solution:
# Set TZ in .env
TZ=America/New_York
# Restart container
docker compose restart devenvGit Clone Fails
Symptom: Cannot clone repositories inside devenv
Solution:
# Check git config
docker exec mks-devenv-full git config --global user.name
docker exec mks-devenv-full git config --global user.email
# Configure GitHub token if needed
docker exec mks-devenv-full gh auth loginGetting Help
Logs
Collect logs when reporting issues:
# All services
docker compose logs > /tmp/devenv-logs.txt
# Specific service
docker compose logs devenv > /tmp/devenv-logs.txt
# Last 100 lines
docker compose logs --tail=100 devenvSystem Information
# Docker version
docker --version
docker compose version
# Container status
docker compose ps
docker stats
# Resource usage
docker stats --no-streamSupport Channels
- GitHub Issues: Create an issue
- Documentation: See Architecture, Configuration
Common Error Messages
| Error | Cause | Solution |
|---|---|---|
port is already allocated | Port conflict | Change port or stop conflicting service |
connection refused | Service not running | Check with supervisorctl status |
database schema not found | Guacamole not initialized | Run cd guacamole && ./init.sh |
permission denied (publickey) | SSH key not configured | Add SSH_PUBLIC_KEY to .env |
OSError: [Errno 28] No space left on device | Disk full | Run docker system prune -a |
Reset Everything
⚠️ WARNING: This deletes all data!
# Stop all services
docker compose down
# Remove all volumes (DELETES DATA)
docker volume rm $(docker volume ls -q)
# Start fresh
docker compose up -d
# Re-initialize Guacamole
cd guacamole && ./init.sh