Troubleshooting Guide

Solutions to common Happy Coder issues.

Installation Issues

"happy: command not found"

Cause: npm global bin directory not in PATH.

Solution:

# Find npm global bin location
npm config get prefix

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

"Claude Code not found"

Cause: Claude Code CLI not installed.

Solution:

# Install Claude Code
npm install -g claude-code

# Verify installation
claude --version

Node.js Version Error

Cause: Node.js version below 18.

Solution:

# Check version
node --version

# Install Node.js 18+ using nvm
nvm install 18
nvm use 18

Connection Issues

QR Code Won't Scan

Problem	Solution
Code too dim	Increase screen brightness to 100%
Camera won't focus	Clean camera lens
Code too small	Run happy --qr-size large
Code expired	Run happy --auth again

Manual Entry Alternative:

happy --no-qr
# Copy the displayed code and enter manually in app

"Status: Disconnected"

Causes & Solutions:

Cause	Solution
CLI not running	Start happy on your computer
Network issues	Check internet connection
Firewall blocking	Whitelist relay server
Corporate proxy	Use cellular data or configure proxy

"Port already in use"

Solution:

# Find what's using the port
lsof -i :8765

# Kill the process
kill -9 <PID>

# Or use a different port
happy --port 8766

Can't Connect to Relay Server

Check firewall settings:

1. Try using cellular data instead of WiFi
2. Ask IT to whitelist relay.happy.engineering
3. Or self-host your relay server

Mobile App Issues

Push Notifications Not Working

iOS:

1. Go to Settings > Happy Coder
2. Enable Notifications
3. Check notification preferences (allow alerts, sounds)

Android:

1. Long-press app icon > App info
2. Tap Notifications
3. Enable all notification categories

Test notifications:

happy notify -p "Test message" -t "Test"

App Crashes on Start

1. Force close the app completely
2. Clear app cache (Android: Settings > Apps > Happy Coder > Storage > Clear Cache)
3. Reinstall the app
4. Re-pair your devices

Session Not Appearing

1. Verify happy is running on your computer
2. Check both devices are on the internet
3. Force refresh session list (pull down)
4. Restart the happy CLI

Voice Coding Issues

Voice Not Recognized

Issue	Solution
Microphone permission denied	Enable in app settings
Wrong language	Change language in voice settings
Background noise	Move to quieter environment
Slow response	Check internet speed

Voice Agent High Cost

The voice agent costs approximately $8/hour (prototype pricing).

To reduce costs:

• Use voice for planning only
• Switch to typing for detailed requests
• Limit voice sessions to short interactions

Session Issues

Context Lost After Long Conversation

Claude Code automatically compacts context in long sessions. This can cause confusion.

Solutions:

1. Start a new session for fresh context
2. Use shorter, focused sessions
3. Reference specific files when context seems lost

Multiple Sessions Interfering

Each session should be in a different directory:

# Good: Separate directories
cd ~/project-a && happy
cd ~/project-b && happy

# Bad: Same directory
cd ~/project && happy
cd ~/project && happy  # Conflict!

Self-Hosting Issues

Docker Container Won't Start

Check environment variables:

docker logs happy-server

Required variables:

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string
• SEED - Token generation seed

SSL/HTTPS Not Working

With Caddy:

# Check Caddy status
sudo systemctl status caddy

# View Caddy logs
sudo journalctl -u caddy -f

# Test certificate
curl -v https://your-domain.com/health

Database Connection Failed

# Test PostgreSQL connection
psql $DATABASE_URL -c "SELECT 1"

# Check PostgreSQL is running
docker ps | grep postgres

Performance Issues

Slow Response Time

Cause	Solution
High latency	Check internet connection
Server overloaded	Self-host your own server
Large files	Exclude large files from Claude context

High Battery Usage (Mobile)

1. Disable background refresh when not needed
2. Close app when not actively using
3. Reduce push notification frequency in settings

Getting Help

Community Resources

• GitHub Issues
• GitHub Discussions

Debug Information

When reporting issues, include:

# Version info
happy --version
node --version
claude --version

# System info
uname -a  # Linux/macOS
systeminfo  # Windows

Reset Everything

If all else fails:

# Remove Happy Coder
npm uninstall -g happy-coder

# Remove config (if any)
rm -rf ~/.happy

# Reinstall
npm install -g happy-coder

# Re-pair devices
happy --auth