Comprehensive guide to diagnosing and fixing common issues with nself v0.3.9.

• Quick Diagnostics
• Installation Issues
• Docker Issues
• Service Issues
• Network Issues
• Database Issues
• SSL/Certificate Issues
• Performance Issues
• Configuration Issues
• Command-Specific Issues
• macOS Compatibility
• Go Module Issues
• Port Conflict Resolution

Always start with these commands:

# Run comprehensive diagnostics
nself doctor

# Check service status
nself status

# View recent logs
nself logs --tail 50

# Validate configuration
nself config validate

Symptoms:

$ nself version
bash: nself: command not found

Solutions:

1. Check if nself is installed:

   ls -la ~/.nself/bin/nself.sh

2. Reinstall nself:

   curl -sSL https://raw.githubusercontent.com/nself-org/cli/main/install.sh | bash

3. Fix PATH manually:

   echo 'export PATH="$HOME/.nself/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

4. For zsh users:

   echo 'export PATH="$HOME/.nself/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

Symptoms:

[ERROR] Cannot write to /usr/local/bin
Permission denied

Solutions:

1. Install to user directory (recommended):

   curl -sSL https://raw.githubusercontent.com/nself-org/cli/main/install.sh | bash

2. System-wide installation (not recommended):

   sudo curl -sSL https://raw.githubusercontent.com/nself-org/cli/main/install.sh | bash

Symptoms:

[ERROR] Docker daemon is not running
Cannot connect to Docker daemon at unix:///var/run/docker.sock

Solutions:

1. macOS/Windows - Start Docker Desktop:

   • Open Docker Desktop application
   • Wait for "Docker Desktop is running" status

2. Linux - Start Docker service:

   sudo systemctl start docker
   sudo systemctl enable docker  # Auto-start on boot

3. Check Docker status:

   docker version
   docker ps

Symptoms:

Got permission denied while trying to connect to Docker daemon socket

Solutions:

1. Add user to docker group (Linux):

   sudo usermod -aG docker $USER
   newgrp docker  # Or logout and login

2. Fix socket permissions:

   sudo chmod 666 /var/run/docker.sock

3. Run with sudo (temporary):

   sudo nself up

Symptoms:

[ERROR] Docker Compose v2 is not available
docker: 'compose' is not a docker command

Solutions:

1. Install Docker Compose v2:

   # macOS/Windows: Update Docker Desktop
   
   # Linux:
   sudo apt update
   sudo apt install docker-compose-plugin

2. Verify installation:

   docker compose version

Symptoms:

[ERROR] Failed to start services
Container nself_postgres_1 exited with code 1

Diagnostic Steps:

1. Check logs:

   nself logs postgres --tail 50

2. Check port conflicts:

   nself doctor  # Will check all ports
   
   # Manual check:
   lsof -i :5432  # PostgreSQL
   lsof -i :8080  # Hasura
   lsof -i :80    # Nginx

3. Reset and retry:

   nself down
   nself up

4. Hard reset if needed:

   nself reset --hard  # WARNING: Deletes data
   nself init
   nself build
   nself up

Symptoms:

Container nself_hasura_1 is restarting, wait until...

Solutions:

1. Check service logs:

   nself logs hasura --tail 100

2. Common causes:

   • Database not ready
   • Invalid configuration
   • Missing environment variables
   • Resource limits

3. Fix configuration:

   nself config validate
   # Fix any reported issues
   nself down
   nself up

Symptoms:

[ERROR] Port 5432 is already in use
bind: address already in use

Solutions:

1. Let auto-fix handle it:

   nself up  # Auto-fix will attempt to resolve

2. Find and stop conflicting process:

   # Find process
   lsof -i :5432
   
   # Stop if it's our container
   docker stop <container_name>
   
   # Stop system PostgreSQL
   sudo systemctl stop postgresql

3. Change port in configuration:

   # Edit .env.local
   POSTGRES_PORT=5433
   
   # Rebuild and restart
   nself build
   nself up

Symptoms:

• Browser shows "This site can't be reached"
• curl https://api.localhost fails

Solutions:

1. Check if services are running:

   nself status

2. Check nginx is running:

   docker ps | grep nginx
   nself logs nginx --tail 20

3. Test direct access:

   # Bypass nginx
   curl http://localhost:8080/healthz  # Hasura
   curl http://localhost:4000/healthz  # Auth

4. Check hosts file:

   # Should have these entries:
   cat /etc/hosts | grep localhost
   # 127.0.0.1 localhost
   # 127.0.0.1 api.localhost auth.localhost storage.localhost

5. Flush DNS cache:

   # macOS
   sudo dscacheutil -flushcache
   
   # Linux
   sudo systemctl restart systemd-resolved
   
   # Windows
   ipconfig /flushdns

Symptoms:

• Browser shows "Your connection is not private"
• NET::ERR_CERT_AUTHORITY_INVALID

Solutions:

1. Trust certificates:

   nself auth ssl trust

2. Regenerate certificates:

   rm -rf nginx/ssl/*
   nself build
   nself auth ssl trust

3. For Chrome - type this in the error page:

   thisisunsafe
   

4. Add certificate exception:

   • Click "Advanced" in browser
   • Click "Proceed to site (unsafe)"

Symptoms:

[ERROR] Connection to database failed
FATAL: password authentication failed for user "postgres"

Solutions:

1. Check database is running:

   nself status
   docker ps | grep postgres

2. Verify credentials:

   # Check .env.local
   grep POSTGRES .env.local

3. Test connection:

   # Using psql
   psql postgresql://postgres:yourpassword@localhost:5432/postgres
   
   # Using docker
   docker exec -it nself_postgres_1 psql -U postgres

4. Reset database:

   nself db reset

Symptoms:

[ERROR] Migration failed
relation "users" already exists

Solutions:

1. Check migration status:

   nself db console
   SELECT * FROM schema_migrations;

2. Reset migrations:

   # Remove migration tracking
   nself db console
   DROP TABLE IF EXISTS schema_migrations;
   
   # Re-run migrations
   nself db migrate

3. Start fresh:

   nself db reset --force
   nself db migrate
   nself db seed

Symptoms:

[WARNING] Certificate expires in -5 days
SSL certificate has expired

Solutions:

1. Regenerate certificates:

   rm -rf nginx/ssl/*
   nself build
   nself auth ssl trust
   nself restart nginx

2. For production - use Let's Encrypt:

   # Install certbot
   sudo apt install certbot
   
   # Generate certificates
   sudo certbot certonly --standalone -d api.yourdomain.com

Symptoms:

• Slow response times
• High CPU/memory usage
• Timeouts

Solutions:

1. Check resource usage:

   nself status  # Shows CPU/memory per service
   docker stats  # Real-time stats

2. Increase resource limits:

   # Edit docker-compose.yml
   services:
     hasura:
       mem_limit: 4g  # Increase from 2g
       cpus: '2.0'    # Increase from 1.0

3. Check for memory leaks:

   # Monitor over time
   watch -n 5 'docker stats --no-stream'

4. Optimize database:

   nself db console
   VACUUM ANALYZE;  # PostgreSQL optimization

Symptoms:

[ERROR] No space left on device

Solutions:

1. Check disk usage:

   df -h
   du -sh *

2. Clean Docker resources:

   # Remove unused images
   docker image prune -a
   
   # Remove unused volumes
   docker volume prune
   
   # Complete cleanup
   docker system prune -a --volumes

3. Remove old backups:

   ls -lah backups/
   rm backups/postgres_*.sql.gz  # Keep recent ones

Symptoms:

[ERROR] Invalid configuration in .env.local
HASURA_GRAPHQL_JWT_SECRET: invalid JSON

Solutions:

1. Validate configuration:

   nself config validate

2. Common fixes:

   # Generate secure passwords
   nself config secrets generate
   
   # Fix JWT secret format
   HASURA_GRAPHQL_JWT_SECRET='{"type":"HS256","key":"32-character-secret-key-here!!!"}'

3. Compare with example:

   diff .env.local .env.example

Symptoms:

• Optional services not starting
• Missing from docker-compose.yml

Solutions:

1. Enable in .env.local:

   REDIS_ENABLED=true
   FUNCTIONS_ENABLED=true
   DASHBOARD_ENABLED=true

2. Rebuild configuration:

   nself build
   nself up

Symptoms:

[ERROR] Cannot initialize in the nself repository!

Solution:

# Create a project directory
mkdir ~/myproject
cd ~/myproject
nself init

Symptoms:

[ERROR] Failed to build Docker images

Solutions:

1. Clear cache and rebuild:

   nself build --no-cache

2. Check Docker disk space:

   docker system df
   docker system prune -a

3. Pull images manually:

   docker pull postgres:15-alpine
   docker pull hasura/graphql-engine:v2.35.0

Symptoms:

[ERROR] Failed to download update

Solutions:

1. Manual update:

   cd ~/.nself
   git pull origin main

2. Reinstall:

   rm -rf ~/.nself
   curl -sSL https://raw.githubusercontent.com/nself-org/cli/main/install.sh | bash

If these solutions don't resolve your issue:

1. Run diagnostics:

   nself doctor > diagnostics.txt
   nself status >> diagnostics.txt
   nself logs --tail 100 >> diagnostics.txt

2. Check GitHub Issues: https://github.com/nself-org/cli/issues

3. Create a new issue with:

   • nself version
   • Operating system
   • Docker version
   • Error messages
   • Diagnostics output

4. Community Support:

   • GitHub Discussions
   • Include output from nself doctor

1. Regular maintenance:

   # Weekly
   docker system prune
   nself doctor
   
   # Monthly
   nself update --check

2. Before production:

   nself config validate
   nself doctor

3. Monitor resources:

   # Add to crontab
   0 * * * * docker stats --no-stream >> /var/log/nself-stats.log

4. Backup regularly:

   # Daily backup
   nself db backup

macOS ships with bash 3.2, which lacks some modern features. nself v0.3.0+ includes full compatibility.

Symptom: "declare: -A: invalid option" errors
Solution: Already fixed in v0.3.0 with automatic fallbacks

Symptom: Script errors with associative arrays
Solution: Update to v0.3.0 or later

nself update

Symptom: Docker not starting automatically
Solution: nself now offers to start Docker Desktop

nself up
# When prompted, choose 'Y' to start Docker Desktop

Symptom: Build fails with "missing go.sum entry for module"
Solution: nself v0.3.0+ handles this automatically

Auto-Fix Options:

1. Run go mod tidy automatically (recommended)
2. Manual fix instructions provided
3. Disable Go services temporarily
4. Rebuild without cache

Manual Fix:

cd services/go/your-service
go mod init your-service  # If no go.mod exists
go mod tidy
go mod download
nself build

Symptom: Go build errors persist after fixes
Solution: Rebuild without cache

nself up
# When prompted after Go errors, choose 'Y' for no-cache rebuild

nself v0.3.0+ includes intelligent port conflict handling.

When conflicts detected, you'll see:

Port conflict options:
  1) Stop conflicting services
  2) Use alternative ports (auto-configure)
  3) Continue anyway (may fail)
  4) Cancel

Automatically finds free ports and updates .env.local:

• Port 80 → 8080, 8081, etc.
• Port 443 → 8443, 8444, etc.
• Port 5432 → 5433, 5434, etc.

Changes are:

• Saved to .env.local
• Applied immediately via auto-rebuild
• Persistent across restarts

Edit .env.local:

NGINX_HTTP_PORT=8080
NGINX_HTTPS_PORT=8443
POSTGRES_PORT=5433
HASURA_PORT=8081

Then rebuild:

nself build
nself up

# View configured ports
grep -E "_PORT=" .env.local

# Check what's using a port
lsof -i :443  # macOS/Linux
netstat -an | grep :443  # Windows

If everything is broken:

# Complete reset
cd ~
rm -rf myproject
docker stop $(docker ps -aq)
docker system prune -a --volumes
mkdir myproject
cd myproject
nself init
nself build
nself up

This will give you a fresh start with no data.