Skip to main content
Common issues with the PraisonAI Gateway daemon and server, with step-by-step troubleshooting guides.

​
Common Issues

​
Daemon Running But Gateway Unreachable

Symptom: praisonai gateway status shows Daemon service: Running (launchd) but Gateway not reachable at http://127.0.0.1:8765/health.
1

Verify daemon is actually running

praisonai gateway status --daemon-only
Look for Running status and process ID.
2

Check daemon logs for errors

praisonai gateway logs

# Or check raw log files:
# macOS: tail ~/.praisonai/logs/bot-stderr.log
# Linux: journalctl --user -u praisonai
Look for Python tracebacks or port binding errors.
3

Check if another process is using the port

lsof -i :8765
# or
netstat -tulpn | grep :8765
If another process is using port 8765, either stop it or change the gateway port.
4

Verify PraisonAI version

praisonai --version
Upgrade to ≥ v4.6.23 if you see older versions - earlier versions had IndentationError bugs fixed in PR #1484.
5

Restart the daemon

# macOS
launchctl kickstart -k gui/$(id -u)/ai.praison.bot

# Linux  
systemctl --user restart praisonai

# Or reinstall completely
praisonai onboard

​
Rapidly Growing Log Files

Symptom: ~/.praisonai/logs/bot-stderr.log grows to multiple MB per minute.
1

Check log file size

ls -lh ~/.praisonai/logs/bot-stderr.log
If growing rapidly (>1MB/min), this indicates a crash loop.
2

View recent errors

tail -50 ~/.praisonai/logs/bot-stderr.log
Look for repeated Python tracebacks, especially IndentationError.
3

Stop the daemon

# macOS
launchctl unload ~/Library/LaunchAgents/ai.praison.bot.plist

# Linux
systemctl --user stop praisonai
4

Clear logs and restart

# Clear the log file
> ~/.praisonai/logs/bot-stderr.log

# Upgrade PraisonAI
pip install --upgrade praisonai

# Restart daemon
praisonai gateway install --start

​
Daemon Not Installed

Symptom: praisonai gateway status shows Daemon service: Not installed (systemd).
1

Run the onboarding wizard

praisonai onboard
This installs the daemon service for your platform.
2

Verify installation

praisonai gateway status --daemon-only
Should show Installed but not running or Running.
3

Start the service

# Manual start
praisonai gateway install --start

# Or check platform-specific commands
praisonai gateway status

​
HTTP 500 on Health Endpoint

Symptom: curl http://127.0.0.1:8765/health returns 500 Internal Server Error.
1

Check PraisonAI version

praisonai --version
Versions before v4.6.23 had AttributeError bugs in the health endpoint.
2

Upgrade PraisonAI

pip install --upgrade praisonai
3

Restart the gateway

praisonai gateway install --start
4

Test health endpoint

curl http://127.0.0.1:8765/health
Should return JSON with status, uptime, agents, sessions, clients, and channels.

​
Permission Denied Errors

Symptom: Daemon fails to start with permission errors in logs. 
# Check LaunchAgent permissions
ls -la ~/Library/LaunchAgents/ai.praison.bot.plist

# Reload LaunchAgent
launchctl unload ~/Library/LaunchAgents/ai.praison.bot.plist
launchctl load ~/Library/LaunchAgents/ai.praison.bot.plist

​
Clean Reinstall Process

When all else fails, perform a clean reinstall:
1

Stop and uninstall

praisonai gateway uninstall
2

Clear configuration

# Backup first if needed
rm -rf ~/.praisonai/logs
rm -rf ~/.praisonai/config
3

Upgrade PraisonAI

pip install --upgrade praisonai
4

Run onboarding

praisonai onboard
Follow the wizard to reinstall the daemon service.
5

Verify installation

praisonai gateway status
Should show daemon running and gateway reachable.

​
Diagnostic Commands

Quick commands for gathering diagnostic information: 
# Full status check
praisonai gateway status

# Daemon-only check (for scripts)
praisonai gateway status --daemon-only

# Recent logs (last 50 lines)
praisonai gateway logs -n 50

# Check port usage
lsof -i :8765

# Test health endpoint directly
curl -v http://127.0.0.1:8765/health

# Check PraisonAI version
praisonai --version

# Platform daemon status
# macOS: launchctl list | grep ai.praison
# Linux: systemctl --user status praisonai
# Windows: schtasks /query /tn "PraisonAI*"

​
Platform-Specific Notes

LaunchAgent Path: ~/Library/LaunchAgents/ai.praison.bot.plist Log Path: ~/.praisonai/logs/bot-stderr.log
# Manual management
launchctl load ~/Library/LaunchAgents/ai.praison.bot.plist
launchctl unload ~/Library/LaunchAgents/ai.praison.bot.plist
launchctl kickstart -k gui/$(id -u)/ai.praison.bot

# Check if loaded
launchctl list | grep ai.praison

Gateway CLI

Gateway command reference

Gateway Server

Gateway configuration and setup