Troubleshooting
Common issues and solutions when using Genbox.
Diagnostic Tools
Run Doctor
gb doctorChecks:
- CLI installation
- Authentication status
- SSH configuration
- Network connectivity
- Project configuration
Verbose Output
Add --debug to any command for detailed output:
gb create my-env --debugCommon Issues
Authentication Issues
”Not logged in"
# Re-authenticate
gb login"Token expired”
# Refresh credentials
gb loginSSH Key Issues
# Check SSH key
ls -la ~/.genbox/
# Regenerate by re-logging in
gb loginCreation Issues
”Configuration validation failed"
# Check configuration
gb validate
# See detailed errors
gb validate --verbose"$detect marker failed"
# See what was detected
cat .genbox/detected.yaml
# Replace with explicit value in genbox.yaml"Server provisioning failed”
- Check your credit balance:
gb balance - Try a smaller size:
--size small - Check API status:
gb doctor
Connection Issues
”Connection refused"
# Check if environment is running
gb status my-env
# If stopped, start it
gb start my-env"SSH permission denied"
# Verify SSH key
ssh-add -l
# Re-login to regenerate keys
gb login"Service not responding”
# Check service status
gb status my-env -v
# View service logs
gb connect my-env -c "pm2 logs"
# Restart services
gb restart my-envDatabase Issues
”Database sync failed"
# Check source environment is defined
gb config show --path environments
# Verify credentials in .env.genbox
cat .env.genbox | grep MONGODB"Connection timeout to MongoDB”
# Check if MongoDB is running
gb connect my-env -c "docker ps | grep mongo"
# Restart MongoDB
gb restart my-env --infraPort Issues
”Port already in use”
When forwarding:
# Check what's using the port locally
lsof -i :27017
# Use different local port
# (manual SSH tunnel)
ssh -L 27018:localhost:27017 my-env.genbox.dev“Service not accessible”
# Verify service is running
gb status my-env
# Check health endpoint
gb connect my-env -c "curl localhost:3050/health"Log Files
Environment Logs
# Application logs
gb connect my-env -c "pm2 logs"
# Specific service
gb connect my-env -c "pm2 logs api"
# System logs
gb connect my-env -c "cat /var/log/genbox/setup.log"Hook Logs
gb connect my-env -c "cat /var/log/genbox/hooks.log"Configuration Debugging
See Resolved Config
gb config showExplain Where Values Come From
gb config show --explainCompare Profiles
gb config diff quick full-stackValidate Configuration
gb validate
gb validate --strictRecovery Procedures
Environment Stuck Starting
# Force destroy and recreate
gb destroy stuck-env --force -y
gb create new-env --profile same-profileServices Won’t Start
# Connect and manually debug
gb connect my-env
# Check logs
pm2 logs
# Try manual start
cd /home/dev/myapp/api
pnpm startDatabase Corrupted
# Rebuild with fresh database
gb rebuild my-env --fresh-db
# Or restore from backup
gb backups list
gb backups restore bkp_xxx --name my-envGetting Help
In-CLI Help
gb help
gb help <command>
gb <command> --helpCheck CLI Version
gb --version
# Update if outdated
gb updateSupport
- Documentation: https://genbox.dev/docsÂ
- Support: https://genbox.dev/supportÂ
- Status: https://status.genbox.devÂ
Share Debug Info
When contacting support, include:
# System info
gb doctor --verbose > doctor-output.txt
# Configuration
gb config show > config-output.txt
# Logs (if environment exists)
gb connect my-env -c "pm2 logs --lines 100" > logs.txtLast updated on