This guide explains common error messages you might encounter and how to resolve them.

Error Message:

✗ Container 'postgres' failed to start

  Reason: Port 5432 is already in use

Solutions:

1. Find and stop the conflicting process:

   # macOS/Linux
   lsof -ti:5432 | xargs kill -9
   
   # Or for specific services
   brew services stop postgresql  # macOS
   sudo systemctl stop postgresql # Linux

2. Change the port in .env.local:

   # Add to .env.local
   POSTGRES_PORT=5433
   
   # Then rebuild and restart
   nself build && nself start

3. Use automatic fix:

   nself doctor --fix

Prevention:

• Use .env.local to override ports that conflict with your system
• Run nself doctor before starting services

Error Message:

✗ Container 'hasura' failed to start

  Reason: Connection to database failed

Solutions:

1. Check logs for detailed error:

   nself logs hasura
   nself logs hasura --tail 100

2. Verify dependencies are running:

   nself status
   docker ps

3. Restart in dependency order:

   nself restart postgres
   sleep 5
   nself restart hasura

4. Full rebuild:

   nself stop
   nself build
   nself start

Common Causes:

• Database not ready when service starts
• Network configuration issues
• Missing environment variables
• Resource constraints (memory/CPU)

Error Message:

✗ Required configuration missing

  File: .env not found or incomplete

  Missing variables:
  • PROJECT_NAME
  • POSTGRES_PASSWORD
  • HASURA_GRAPHQL_ADMIN_SECRET

Solutions:

1. Initialize configuration:

   nself init

2. Copy from example:

   cp .env.example .env
   # Edit .env with your values

3. Validate and auto-fix:

   nself config validate --fix

Required Variables:

• PROJECT_NAME - Your project identifier
• POSTGRES_PASSWORD - Database password
• HASURA_GRAPHQL_ADMIN_SECRET - Hasura admin secret
• BASE_DOMAIN - Your domain (default: local.nself.org)

Error Message:

✗ Permission denied

  Cannot access: /var/run/docker.sock

Solutions:

1. Fix file ownership:

   sudo chown -R $(whoami) ./

2. Add user to docker group (Linux):

   sudo usermod -aG docker $USER
   # Log out and back in

3. Check Docker is running:

   docker info

4. macOS - Restart Docker Desktop:

   • Docker Desktop handles permissions automatically
   • If issues persist, restart Docker Desktop

Common Causes:

• Docker daemon not running
• User not in docker group (Linux)
• File ownership issues
• Insufficient sudo privileges

Error Message:

✗ Network connection failed

  Service: hasura
  URL: http://localhost:8080
  Error: connection refused

Solutions:

1. Check service is running:

   docker ps | grep hasura

2. Check Docker networking:

   docker network ls
   docker network inspect nself_default

3. Restart Docker networking:

   nself stop
   docker network prune -f
   nself start

4. Test connectivity:

   curl -v http://localhost:8080

Common Causes:

• Service not started
• Port mapping incorrect
• Firewall blocking connections
• VPN interfering with Docker networking

Error Message:

✗ Docker is not running

Solutions:

macOS:

# Start Docker Desktop
open -a Docker

# Wait 10-15 seconds for initialization

# Verify
docker info

Linux:

# Start Docker service
sudo systemctl start docker

# Enable on boot
sudo systemctl enable docker

# Verify
docker info

Windows:

• Start Docker Desktop from Start Menu
• Or run: "C:\Program Files\Docker\Docker\Docker Desktop.exe"

Error Message:

✗ Insufficient memory

  Available: 2GB
  Required: 4GB

Solutions:

1. Close unnecessary applications

2. Increase Docker memory (macOS):

   • Docker Desktop → Settings → Resources → Memory
   • Recommended: 4GB minimum, 8GB optimal

3. Disable optional services:

   # In .env.local
   MONITORING_ENABLED=false
   MLFLOW_ENABLED=false
   REDIS_ENABLED=false

4. Check disk space:

   df -h .
   docker system df

5. Clean Docker resources:

   docker system prune -a --volumes
   nself clean

Error Message:

✗ Database connection failed

  Database: PostgreSQL
  Error: connection refused

Solutions:

1. Check if database is running:

   docker ps | grep postgres
   nself logs postgres

2. Verify connection settings in .env:

   POSTGRES_PORT=5432
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=<your-password>
   POSTGRES_DB=nhost

3. Check for port conflicts:

   lsof -i :5432

4. Restart database:

   nself restart postgres
   sleep 5
   nself status

5. Test connection:

   docker exec -it ${PROJECT_NAME}_postgres psql -U postgres

Connection URL Format:

postgresql://user:password@localhost:5432/database

Error Message:

✗ Build failed for 'custom-service'

  Stage: RUN npm install
  Error: ENOENT: no such file or directory

Solutions:

1. Check Dockerfile syntax:

   cat services/custom-service/Dockerfile

2. Clean build cache:

   docker builder prune -f
   nself build --no-cache

3. Check disk space:

   df -h
   docker system df

4. Rebuild specific service:

   docker-compose build custom-service

5. Check Docker daemon logs:

   • macOS: Docker Desktop → Troubleshoot → View logs
   • Linux: journalctl -u docker.service

Common Causes:

• Syntax errors in Dockerfile
• Missing files in build context
• Network issues downloading dependencies
• Insufficient disk space
• Build cache corruption

Error Message:

✗ Service 'hasura' is unhealthy

  Possible solutions:
  1. Check service logs for errors
  2. Verify dependencies are running
  3. Restart the service

Solutions:

1. Check detailed logs:

   nself logs hasura --tail 50

2. Inspect container:

   docker inspect ${PROJECT_NAME}_hasura

3. Check dependencies:

   nself status

4. Restart service:

   nself restart hasura

5. Monitor resources:

   docker stats ${PROJECT_NAME}_hasura

Note: Some services take 30-60 seconds to become healthy after starting.

nself doctor

nself doctor --verbose

nself doctor --fix

nself logs <service>
nself logs <service> --tail 100
nself logs <service> --follow

nself status
nself status --detailed

docker ps -a
docker stats
docker inspect ${PROJECT_NAME}_<service>

1. Always run nself doctor before starting

   • Checks system requirements
   • Identifies potential issues
   • Suggests fixes

2. Use .env.local for customizations

   • Override ports that conflict
   • Set machine-specific values
   • Keep .env clean

3. Monitor resource usage

   docker stats
   df -h
   free -h  # Linux

4. Keep Docker updated

   docker --version
   docker compose version

5. Regular cleanup

   nself clean
   docker system prune -a

• Main docs: docs/README.md
• Configuration: docs/configuration/
• Troubleshooting: docs/troubleshooting/

nself help
nself <command> --help

• GitHub Issues: github.com/nself-org/cli/issues
• Discussions: github.com/nself-org/cli/discussions

All nself error messages follow this format for consistency:

✗ [Problem Statement]

  Reason: [Specific cause]

  Possible solutions:
  1. [Primary solution with command]

  2. [Alternative solution]

  3. [Automatic fix if available]

  Run 'nself doctor' for more diagnostics

This format ensures:

• Clear problem statement - What went wrong
• Specific reason - Why it failed
• Actionable solutions - How to fix it (numbered)
• Command examples - Copy-paste ready
• Additional help - Where to get more info

Found an unclear error message? Please:

1. Open an issue with the error message
2. Describe what was confusing
3. Suggest improvements

Error messages are continually improved based on user feedback.