Quick Start
1
Read the startup pill
The pill shows
starting engine, then engine :PORT on success or engine failed with a tail on failure.2
Open the engine log
The log viewer shows the engine’s recent activity — a bounded 400-line ring buffer — without leaving the app.
3
Reset the engine if it's stuck
Close the app, delete the lockfile in the data directory, and relaunch.
Startup States
On failure, the tail comes from the supervisor’s 12-line buffer, so you see the actual error rather than a bare exit code.
Common Failures
engine failed: missing dependency
engine failed: missing dependency
The venv has no
praisonaiagents (or a native wheel is broken). The engine reports ModuleNotFoundError / ImportError. Install the SDK into the venv the app resolves:engine failed: address in use
engine failed: address in use
Another PraisonAI process holds the port (
Address already in use). Quit the other process, or reset the engine and relaunch.engine failed: crashed
engine failed: crashed
An unhandled exception reached the top of the stack. The tail is shown — open the Engine Log for the full 400-line buffer.
No virtual environment found
No virtual environment found
The app checks
src/praisonai-agents/.venv, src/praisonai-agents/venv, then venv. Create one of these and install praisonaiagents into it.Updates
The update check currently reports “Update checks are not configured yet.” — an auto-update feed isn’t wired in yet, and the app says so rather than falsely reporting “up to date”.check_updates can be on, but until a release feed is configured the check will honestly report that it is not set up.Reset Recipe
1
Quit the app
Fully close the window so the engine process exits.
2
Delete the lockfile
Remove the lockfile in
~/Library/Application Support/PraisonAI.3
Relaunch
Reopen the app — the shell spawns a fresh engine and the pill returns to
starting engine.Best Practices
Check the log before filing a ticket
Check the log before filing a ticket
The engine log is a 400-line ring buffer of recent activity. It usually names the failure directly.
Keep one PraisonAI process at a time
Keep one PraisonAI process at a time
“Address in use” comes from a second process on the port. Close extras before relaunching.
Match the interpreter to its venv
Match the interpreter to its venv
The shell refuses an interpreter whose site-packages live outside its own venv. Use a clean
.venv inside the checkout to avoid mismatches.Related
Overview
Install, launch, and how the engine starts
Data & Privacy
Where the data directory and lockfile live