Documentation Index Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
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.
Verify daemon is actually running
praisonai gateway status --daemon-only
Look for Running status and process ID.
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-bot
Look for Python tracebacks or port binding errors.
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.
Verify PraisonAI version
Upgrade to ≥ v4.6.23 if you see older versions - earlier versions had IndentationError bugs fixed in PR #1484.
Restart the daemon
# macOS launchctl kickstart -k gui/ $( id -u ) /ai.praison.bot # Linux systemctl --user restart praisonai-bot # Or reinstall completely praisonai onboard
Rapidly Growing Log Files Symptom: ~/.praisonai/logs/bot-stderr.log grows to multiple MB per minute.
Check log file size
ls -lh ~/.praisonai/logs/bot-stderr.log
If growing rapidly (>1MB/min), this indicates a crash loop.
View recent errors
tail -50 ~/.praisonai/logs/bot-stderr.log
Look for repeated Python tracebacks, especially IndentationError.
Stop the daemon
# macOS launchctl unload ~/Library/LaunchAgents/ai.praison.bot.plist # Linux systemctl --user stop praisonai-bot
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).
Run the onboarding wizard
This installs the daemon service for your platform.
Verify installation
praisonai gateway status --daemon-only
Should show Installed but not running or Running.
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.
Check PraisonAI version
Versions before v4.6.23 had AttributeError bugs in the health endpoint.
Upgrade PraisonAI
pip install --upgrade praisonai
Restart the gateway
praisonai gateway install --start
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
# Check systemd user service systemctl --user status praisonai-bot # Enable user lingering (allows services to run when not logged in) sudo loginctl enable-linger $( whoami ) # Restart service systemctl --user daemon-reload systemctl --user restart praisonai-bot
# Run as administrator # Check Task Scheduler for PraisonAI task schtasks / Query / TN PraisonAIGateway # Delete and recreate praisonai gateway uninstall praisonai gateway install
Clean Reinstall Process When all else fails, perform a clean reinstall:
Stop and uninstall
praisonai gateway uninstall
Clear configuration
# Backup first if needed rm -rf ~/.praisonai/logs rm -rf ~/.praisonai/config
Upgrade PraisonAI
pip install --upgrade praisonai
Run onboarding
Follow the wizard to reinstall the daemon service.
Verify installation
Should show daemon running and gateway reachable. Authentication Errors GatewayStartupError: Cannot bind to 0.0.0.0 without an auth token Symptom: Gateway fails to start when binding to external interfaces without authentication.
Use onboarding wizard
This automatically generates and saves a secure token.
Or set token manually
export GATEWAY_AUTH_TOKEN =$( openssl rand -hex 16 ) praisonai gateway start --host 0.0.0.0
UIStartupError: Cannot bind to 0.0.0.0 with default admin/admin credentials Symptom: Chainlit UI fails to start on external interface with default credentials.
Set custom credentials
export CHAINLIT_USERNAME = myuser export CHAINLIT_PASSWORD = mypass praisonai chat --host 0.0.0.0
Or allow defaults for demos (unsafe)
export PRAISONAI_ALLOW_DEFAULT_CREDS = 1 praisonai chat --host 0.0.0.0
My gateway logs show gw_****xxxx instead of the full token This is intentional for security — tokens are fingerprinted in logs to prevent exposure.
Retrieve full token from environment file
cat ~/.praisonai/.env | grep GATEWAY_AUTH_TOKEN
Or check environment variables
Restart After Config Change When you update bot configuration files, restart the daemon using these OS-specific commands (matching the onboard Done panel):
launchctl kickstart -k gui/ $( id -u ) /ai.praison.bot
systemctl --user restart praisonai-bot
schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway
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-bot # Windows: schtasks /Query /TN PraisonAIGateway
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
Service Path: ~/.config/systemd/user/praisonai-bot.service
Logs: journalctl --user -u praisonai-bot# Manual management systemctl --user start praisonai-bot systemctl --user stop praisonai-bot systemctl --user restart praisonai-bot systemctl --user enable praisonai-bot # Check status systemctl --user status praisonai-bot
Task Path: Task Scheduler → PraisonAIGateway
Logs: Windows Event Log# Manual management via Task Scheduler or: schtasks / Run / TN PraisonAIGateway schtasks / End / TN PraisonAIGateway # Check status schtasks / Query / TN PraisonAIGateway
Gateway CLI Gateway command reference
Gateway Server Gateway configuration and setup
