Troubleshooting

This guide helps you diagnose and resolve common issues with Happy CLI. The happy doctor command is your first stop for automated diagnostics.

Doctor Command

The doctor command provides comprehensive system diagnostics:

happy doctor

This displays:

Happy CLI version and platform info
Configuration and environment variables
Authentication status
Daemon status and process list
Recent log files
Support links

Doctor Output

Example output:

🩺 Happy CLI Doctor

📋 Basic Information
Happy CLI Version: 1.0.0
Platform: darwin arm64
Node.js Version: v20.11.0

⚙️  Configuration
Happy Home: /Users/john/.happy
Server URL: https://api.cluster-fluster.com
Logs Dir: /Users/john/.happy/logs

🌍 Environment Variables
HAPPY_HOME_DIR: not set
HAPPY_SERVER_URL: not set
DEBUG: not set
NODE_ENV: not set

🔐 Authentication
✓ Authenticated (credentials found)

🤖 Daemon Status
✓ Daemon is running
  PID: 12345
  Started: 3/4/2026, 2:30:45 PM
  CLI Version: 1.0.0
  HTTP Port: 50097

🔍 All Happy CLI Processes

📍 Current Process:
  PID 12399: /usr/local/bin/node .../dist/index.mjs doctor

🤖 Daemon:
  PID 12345: /usr/local/bin/node .../dist/index.mjs daemon start-sync

🔗 Daemon-Spawned Sessions:
  PID 12350: /usr/local/bin/node .../dist/index.mjs --started-by daemon

📝 Log Files

Recent Logs:
  2026-03-04-14-35-22.log - 3/4/2026, 2:35:22 PM
    /Users/john/.happy/logs/2026-03-04-14-35-22.log

Daemon Logs:
  2026-03-04-14-30-45-daemon.log - 3/4/2026, 2:30:45 PM
    /Users/john/.happy/logs/2026-03-04-14-30-45-daemon.log

🐛 Support & Bug Reports
Report issues: https://github.com/slopus/happy-cli/issues
Documentation: https://happy.engineering/

✅ Doctor diagnosis complete!

Daemon-Only Diagnostics

Focus on daemon-related issues:

happy daemon status

Shows only daemon status and process information.

Common Issues

Authentication Problems

Error: Not authenticated

Symptoms: Error: Not authenticated when running happyDiagnosis:

happy auth status

Solution:

happy auth login

If already authenticated but still seeing errors:

happy auth login --force

Authentication hangs at 'Waiting for authentication'

Symptoms: CLI stuck polling for authenticationCauses:

Mobile app not responding to QR code
Network connectivity issues
Server timeout

Solution:

Press Ctrl+C to cancel
Check network connection:
```
ping api.cluster-fluster.com
```
Try web authentication instead of mobile
Check firewall/proxy settings

QR code not displaying correctly

Symptoms: Garbled QR code in terminalCauses:

Terminal doesn’t support unicode
Font size too small
Color scheme interference

Solution:

Increase terminal font size
Use manual URL shown below QR code
Switch to web authentication
Try a different terminal emulator

Daemon Issues

Daemon won't start

Symptoms: Daemon already running but daemon status shows not runningDiagnosis:

happy daemon status

Solution:

# Clean up stale state
rm ~/.happy/daemon.state.json
rm ~/.happy/daemon.lock

# Restart daemon
happy daemon start

Daemon version mismatch

Symptoms: Daemon version mismatch detected in logsCause: Happy CLI was upgraded but daemon still running old versionSolution: Daemon should auto-restart. If not:

happy daemon stop
happy daemon start

Multiple daemon processes running

Symptoms: happy daemon list shows duplicate entries or errorsDiagnosis:

happy doctor
# Look for multiple daemon processes

Solution:

# Kill all runaway processes
happy doctor clean

# Restart daemon cleanly
happy daemon start

Session Problems

Session won't start

Symptoms: Happy starts but Claude doesn’t launchDiagnosis:

# Check logs
tail -f ~/.happy/logs/$(ls -t ~/.happy/logs/*.log | head -1)

Common causes:

Claude Code not installed:

npm install -g @anthropic-ai/claude-code

Authentication expired:
```
happy auth login --force
```
Sandbox blocking execution:
```
happy --no-sandbox
```

Session stuck in 'thinking' state

Symptoms: Session appears frozen, no responsesDiagnosis:

# Check if Claude process is alive
ps aux | grep claude

# Check session logs
tail -f ~/.happy/logs/*.log

Solution:

# Stop session via daemon
happy daemon list  # Get session ID
happy daemon stop-session <session-id>

# Or kill all Happy processes
happy doctor clean

Can't resume session

Symptoms: --resume flag doesn’t restore previous conversationCheck:

# List Claude sessions
ls -lt ~/.claude/projects/*/

Note: Resume creates a NEW session ID with copied history. This is expected Claude Code behavior.Workaround: Use the session ID shown in previous session output.

Network and Connectivity

Can't connect to Happy servers

Symptoms: Connection errors, timeoutsDiagnosis:

# Test connectivity
curl -I https://api.cluster-fluster.com

# Check environment
happy doctor

Solutions:

Check firewall settings
Verify proxy configuration

Test with custom server:

export HAPPY_SERVER_URL=http://localhost:3005
happy

WebSocket connection fails

Symptoms: Sessions start but don’t sync to mobileDiagnosis: Check daemon logs:

tail -f $(happy daemon logs)

Solutions:

Restart daemon:

happy daemon stop && happy daemon start

Check firewall allows WebSocket connections
Verify authentication:
```
happy auth status
```

File System and Sandbox

Permission denied errors

Symptoms: Claude can’t read/write filesDiagnosis:

# Check sandbox configuration
happy sandbox status

Solutions:

Temporarily disable sandbox:
```
happy --no-sandbox
```
Reconfigure sandbox:
```
happy sandbox configure
```
Check file permissions:
```
ls -la <problematic-file>
```

Can't access workspace directory

Symptoms: Sandbox blocks access to project filesCheck configuration:

cat ~/.happy/settings.json | jq '.sandboxConfig'

Solution: Update workspace root:

happy sandbox configure
# Select correct workspace directory

Process Management

Viewing Processes

See all Happy-related processes:

happy doctor
# Scroll to "All Happy CLI Processes" section

Process types:

Current Process: The doctor command itself
Daemon: Background service
Daemon-Spawned Sessions: Remote-controlled sessions
User Sessions: Terminal-launched sessions
Doctor: Diagnostic commands

Cleaning Up Processes

Kill all runaway Happy processes:

happy doctor clean

This finds and kills:

Stale daemon processes
Hung version check processes
Orphaned session processes
Zombie processes

Example output:

Killing runaway process PID 12340: /usr/local/bin/node .../daemon start-sync
Successfully killed runaway process PID 12340
Killing runaway process PID 12341: /usr/local/bin/node .../--started-by daemon
Successfully killed runaway process PID 12341
Cleaned up 2 runaway processes

happy doctor clean kills ALL Happy processes except the current one. Active sessions will be terminated.

Manual Process Management

Find Happy processes manually:

# All Happy processes
ps aux | grep happy

# Only daemon
ps aux | grep "daemon start"

# Only sessions
ps aux | grep "started-by"

Kill specific process:

# Graceful
kill <pid>

# Force kill
kill -9 <pid>

Log Analysis

Finding Logs

Log location:

# Default
~/.happy/logs/

# Custom (if HAPPY_HOME_DIR set)
$HAPPY_HOME_DIR/logs/

List recent logs:

# All logs
ls -lt ~/.happy/logs/*.log

# Session logs only
ls -lt ~/.happy/logs/*.log | grep -v daemon

# Daemon logs only
ls -lt ~/.happy/logs/*daemon.log

Viewing Logs

Tail latest session log:

tail -f ~/.happy/logs/$(ls -t ~/.happy/logs/*.log | grep -v daemon | head -1)

Tail daemon log:

tail -f $(happy daemon logs)

Search logs for errors:

grep -i error ~/.happy/logs/*.log
grep -i "failed" ~/.happy/logs/*.log
grep -i "exception" ~/.happy/logs/*.log

Log Format

Logs include:

Timestamp
Log level (DEBUG, INFO, ERROR)
Component (DAEMON, AUTH, SESSION, etc.)
Message
Stack traces (for errors)

Example:

[2026-03-04 14:30:45] [INFO] [DAEMON RUN] Starting daemon process...
[2026-03-04 14:30:46] [DEBUG] [DAEMON RUN] Environment: {...}
[2026-03-04 14:30:47] [INFO] [DAEMON RUN] Daemon started successfully
[2026-03-04 14:35:12] [ERROR] [SESSION] Failed to connect to Claude: ECONNREFUSED
  at Socket.<anonymous> (/path/to/file.ts:123:45)
  ...

Debug Mode

Enable detailed logging:

export DEBUG=1
happy

This outputs:

Detailed execution flow
API request/response data
WebSocket messages
Internal state changes

View debug logs:

tail -f ~/.happy/logs/$(ls -t ~/.happy/logs/*.log | head -1)

Environment Diagnostics

Check Environment

View all environment variables:

happy doctor | grep -A 20 "Environment Variables"

Important variables:

# Happy configuration
echo $HAPPY_HOME_DIR
echo $HAPPY_SERVER_URL
echo $HAPPY_PROJECT_ROOT

# Debugging
echo $DEBUG
echo $NODE_ENV

# Authentication
echo $HAPPY_DAEMON_HEARTBEAT_INTERVAL

Verify Installation

Check Happy CLI is properly installed:

# Version
happy --version

# Which binary
which happy

# Installation location
npm list -g happy-coder
# or
yarn global list | grep happy

Check Dependencies

Verify required tools:

# Node.js
node --version

# npm/yarn
npm --version
yarn --version

# Claude Code
claude --version

Advanced Troubleshooting

State File Corruption

If daemon state is corrupted:

# Backup current state
cp ~/.happy/daemon.state.json ~/.happy/daemon.state.json.bak

# Remove corrupted state
rm ~/.happy/daemon.state.json

# Restart daemon
happy daemon start

Lock File Issues

If lock file is stuck:

# Check lock file
cat ~/.happy/daemon.lock

# Verify PID is not running
ps -p <pid-from-lock-file>

# Remove stale lock
rm ~/.happy/daemon.lock

Reset to Factory Defaults

Completely reset Happy:

# Stop daemon
happy daemon stop

# Backup data (optional)
cp -r ~/.happy ~/.happy.backup

# Remove all Happy data
rm -rf ~/.happy

# Re-authenticate
happy auth login

This removes all credentials, settings, and logs. You’ll need to re-authenticate and reconfigure.

Getting Help

Report Issues

When reporting bugs, include:

System info:
```
happy doctor > happy-diagnosis.txt
```

Relevant logs:

tail -100 ~/.happy/logs/$(ls -t ~/.happy/logs/*.log | head -1) > error-log.txt

Steps to reproduce
Expected vs actual behavior

Support Channels

GitHub Issues: https://github.com/slopus/happy-cli/issues
Documentation: https://happy.engineering/
Community: Join our Discord/Slack (link in docs)

Debug Checklist

Before asking for help, verify:

Ran happy doctor and reviewed output
Checked authentication: happy auth status
Verified daemon: happy daemon status
Reviewed recent logs
Tried happy doctor clean
Tested with --no-sandbox
Checked network connectivity
Verified Node.js version (>= 18)
Claude Code is installed and working

happy auth status - Check authentication
happy daemon status - Check daemon
happy sandbox status - Check sandbox

Get Started

Core Features

Guides

Components

Troubleshooting

Troubleshooting

Doctor Command

Doctor Output

Daemon-Only Diagnostics

Common Issues

Authentication Problems

Daemon Issues

Session Problems

Network and Connectivity

File System and Sandbox

Process Management

Viewing Processes

Cleaning Up Processes

Manual Process Management

Log Analysis

Finding Logs

Viewing Logs

Log Format

Debug Mode

Environment Diagnostics

Check Environment

Verify Installation

Check Dependencies

Advanced Troubleshooting

State File Corruption

Lock File Issues

Reset to Factory Defaults

Getting Help

Report Issues

Support Channels

Debug Checklist

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Components

​Troubleshooting

​Doctor Command

​Doctor Output

​Daemon-Only Diagnostics

​Common Issues

​Authentication Problems

​Daemon Issues

​Session Problems

​Network and Connectivity

​File System and Sandbox

​Process Management

​Viewing Processes

​Cleaning Up Processes

​Manual Process Management

​Log Analysis

​Finding Logs

​Viewing Logs

​Log Format

​Debug Mode

​Environment Diagnostics

​Check Environment

​Verify Installation

​Check Dependencies

​Advanced Troubleshooting

​State File Corruption

​Lock File Issues

​Reset to Factory Defaults

​Getting Help

​Report Issues

​Support Channels

​Debug Checklist

​Related Commands

Build docs developers (and LLMs) love

Troubleshooting

Doctor Command

Doctor Output

Daemon-Only Diagnostics

Common Issues

Authentication Problems

Daemon Issues

Session Problems

Network and Connectivity

File System and Sandbox

Process Management

Viewing Processes

Cleaning Up Processes

Manual Process Management

Log Analysis

Finding Logs

Viewing Logs

Log Format

Debug Mode

Environment Diagnostics

Check Environment

Verify Installation

Check Dependencies

Advanced Troubleshooting

State File Corruption

Lock File Issues

Reset to Factory Defaults

Getting Help

Report Issues

Support Channels

Debug Checklist

Related Commands