Desktop v4.7.3 Windows — engine never starts; UI stuck at setup needed (Chat / Train / Settings unusable)

[Dhivya-Bharathy]

[BUG] Desktop v4.7.3 Windows — engine never starts; UI stuck at “setup needed” (Chat / Train / Settings unusable)

Metadata

Field	Value
Repository	https://github.com/MervinPraison/PraisonAI
Component	src/praisonai-desktop (engine supervisor + first-run UI)
Release tested	v4.7.3
Asset	PraisonAI-v4.7.3-windows-x64-setup.exe
Install path	%LOCALAPPDATA%\PraisonAI\
Data path	%APPDATA%\PraisonAI\
Labels	bug, desktop, windows, engine, first-run, ux
Severity	High — app looks installed but core features are dead
Discovered	2026-08-27 automated E2E + end-user confirmation (screenshot)
Screenshot	Attach when filing on GitHub — drag image into issue body

---

Executive summary

PraisonAI Desktop on Windows is a two-process application:

Process	Location	Role
Shell	%LOCALAPPDATA%\PraisonAI\praisonai-desktop.exe	Tauri + WebView2 UI; must spawn and supervise engine
Engine	%LOCALAPPDATA%\PraisonAI\engine\server.py	Loopback HTTP on 127.0.0.1 — Chat, Settings, Train, logs

v4.7.3 INSTALL.md documents:

On first run the app offers to build a Python environment via uv (~500 MB once), shows progress, then starts the loopback engine automatically.

Live result on Windows 10 x64: the shell opens a full UI, but the engine never binds. Users see title-bar status setup needed. Opening Settings shows modal “Settings needs the engine”. Chat, Train, and Settings are unusable.

Test	Shell	engine.lock	server.py process	/health
Normal install + launch	Running	Absent	None	Unreachable
End-user session (screenshot)	Running, setup needed	Absent	None	Blocked
Manual python engine\server.py	N/A	Written	Running	{"ok":true}

Verdict: product/developer defect — not user misconfiguration. Engine code works when started manually. Supervisor and first-run UI fail on the shipped Windows build.

---

End-user evidence — attach screenshot when filing

When filing on GitHub: drag-and-drop your screenshot into the issue body. Do not link repo-local or machine-local paths — reviewers only see what you attach.

Observed UI (2026-08-27, v4.7.3 Windows)

UI element	Observed state	Implication
Window title	PraisonAI (dark theme)	Shell launched successfully
Title-bar status badge	setup needed	Engine not ready; provisioning incomplete or never started
Model selector	Select model (dropdown)	Inactive — needs engine for model list
Active sidebar tab	Train (green highlight)	Training UI rendered
Train — Dataset	yahma/alpaca-cleaned	Default form values visible
Train — Split	train
Train — Epochs	1
Train — Max Steps	60
Start training button	Visible (green)	Cannot run — no loopback engine
Settings modal title	Settings needs the engine	User opened Settings (sidebar or Ctrl+,)
Settings modal body	“The engine is not running, so there is nothing to read yet. The status in the title bar says why it failed to start.”	App acknowledges failure
Modal actions	Close only	No “Start setup”, “Retry engine”, “View engine log”
Sidebar nav	Chat, Train, New chat (Ctrl+N), Search (Ctrl+K)
Sidebar footer	Engine log, Settings (Ctrl+,)	Engine log exists but not suggested in modal

User journey (confirmed)

1. Install v4.7.3 from GitHub Releases.
2. Launch PraisonAI — window appears (not a crash).
3. Title bar shows setup needed — no setup wizard visible.
4. Navigate to Train — form looks complete and usable.
5. Open Settings — blocked by modal; told to check title bar.
6. Title bar only says setup needed — no explanation, no fix button.
7. Cannot start engine through any normal product UI.

---

Environment

Field	Value
OS	Windows 10 build 19045, x64
Release	v4.7.3
Installer	PraisonAI-v4.7.3-windows-x64-setup.exe
Python (manual test)	3.13 on system PATH — engine works when started manually
Code signing	Unsigned (expected per release notes)

---

Step-by-step reproduction

Path A — end user (matches screenshot)

1. Install v4.7.3 Windows setup.
2. Launch from Start Menu or %LOCALAPPDATA%\PraisonAI\praisonai-desktop.exe.
3. Wait 60+ seconds — title bar still setup needed.
4. Click Train — form renders with dataset defaults.
5. Click Settings — modal Settings needs the engine → only Close.
6. Click Start training — no progress (engine not listening).
7. Optional: open Engine log in sidebar — may show spawn errors (user must discover).

Path B — developer verification

# Shell running but engine absent
Test-Path "$env:APPDATA\PraisonAI\engine.lock"                    # False
Get-CimInstance Win32_Process |
  Where-Object { $_.CommandLine -like '*server.py*' }             # empty
Get-Process praisonai-desktop -ErrorAction SilentlyContinue       # running

Wait 60+ seconds after launch — still no lockfile, no server.py child.

Path C — control (proves engine bundle OK)

python "$env:LOCALAPPDATA\PraisonAI\engine\server.py"
# stdout: PRAISONAI_PORT=<port>
Invoke-RestMethod "http://127.0.0.1:<port>/health"

Live results:

Endpoint / action	Result
/health	{"ok":true,"version":2,...}
SSE POST /chat	Model response in ~19 s
Chat persistence	Saved under %APPDATA%\PraisonAI
/update	praisonaiagents 1.7.1 current on PyPI

Example lockfile after manual start:

format_version=2
pid=<pid>
port=<port>
interpreter=<path-to-python.exe>
venv_root=<venv-or-python-root>
config_hash=<hash>

---

Expected vs actual

Step	Expected (INSTALL.md + release notes)	Actual v4.7.3 Windows
Post-install launch	First-run setup offers uv env build	setup needed, no visible wizard
Python discovery	Detect ≥3.10 or prompt download	Stuck; no actionable UI
Engine supervisor	Spawn server.py, parse PRAISONAI_PORT=	Never spawns
Lockfile	%APPDATA%\PraisonAI\engine.lock	Absent until manual start
Title bar status	ready or explicit provisioning step	setup needed indefinitely
Settings	API keys, models, paths	Modal: engine not running
Chat composer	Active	Blocked (engine dependency)
Train tab	Start training runs via engine HTTP	Form visible; cannot execute
Failure UX	In-app error + Engine log link	Modal → title bar; insufficient

---

Architecture

flowchart TD
    subgraph intended
        L[Launch shell] --> S[Setup / detect Python]
        S --> P[Spawn server.py]
        P --> K[Write engine.lock]
        K --> R[Status: ready]
        R --> U[Chat Train Settings work]
    end
    subgraph live_bug
        L2[Launch shell] --> B[setup needed badge]
        B --> UI[UI renders Chat Train Settings]
        B -.->|never| P2[server.py]
        UI --> M[Settings modal dead-end]
    end

Loading

sequenceDiagram
    participant U as User
    participant UI as WebView
    participant S as Supervisor
    U->>UI: Settings
    UI->>U: Modal — engine not running
    Note over S: server.py never spawned

Loading

---

Why users blame themselves (incorrectly)

Misleading signal	User assumption	Reality
Polished window opens	Install succeeded fully	Only shell loaded
Train form complete	Can start training	Requires loopback engine
Modal: “check title bar”	Detailed reason shown	Only setup needed — no how-to
No crash / no SmartScreen	Must be API key or Python	Supervisor never started engine
Close modal	Problem dismissed	Engine still down

---

Root cause (hypothesis — needs Rust + frontend confirm)

Ranked by likelihood:

1. provision_engine / setup screen never shown despite engine_status = setup needed. first-run.test.mjs tests mocked UI only — not real Windows supervisor after NSIS install.

2. Python PATH differs for GUI vs terminal — Store Python, py launcher, or user PATH not visible to praisonai-desktop.exe launched from Start Menu.

3. Partial AppData state — %APPDATA%\PraisonAI exists but provision incomplete; app stuck without retry (related: silent exit when AppData fully missing on same release).

4. No blocking gate — user navigates Train/Chat while engine permanently down; looks usable, is not.

---

Suggested fix

P0 — unblock users

• Full-page Complete setup when engine not ready; redirect or disable Train/Chat until ready.
• Settings modal: add Open setup, Retry engine, View engine log — not Close-only.
• Supervisor must spawn or attach within timeout; on failure write %APPDATA%\PraisonAI\logs\engine-start.log.
• Make setup needed badge clickable → provisioning wizard.

P1 — Windows hardening

• Log PATH and Python discovery in Engine log (user-visible).
• Use existing Python one-click when ≥3.10 found (optional skip of 500 MB uv download).
• Windows CI: launch built .exe, assert engine.lock within 120 s.

P2 — tests

• Extend desktop tests: setup needed → setup CTA → mock provision → ready.
• Real .exe smoke on Windows release agent (not mocked engine_status only).

---

Acceptance criteria

• Fresh v4.7.3 Windows install → setup completes without manual python server.py
• %APPDATA%\PraisonAI\engine.lock within 2 min of setup
• Title bar shows ready
• Settings opens without “engine not running” modal
• Chat composer and Train → Start training reach engine (or show explicit API-key error)
• Engine failure shows actionable recovery UI
• INSTALL.md troubleshooting updated

---

Workaround (developer only — not for end users)

# Keep this terminal open
python "$env:LOCALAPPDATA\PraisonAI\engine\server.py"

Note PRAISONAI_PORT= line. Reload PraisonAI; shell may attach via lockfile. Check sidebar Engine log for spawn errors. Do not document as primary install path.

---

What worked on same build (scope boundary)

Item	Status
NSIS install to %LOCALAPPDATA%\PraisonAI	OK
Engine bundle (engine\server.py, routes, training)	OK
Manual engine /health, /settings, /chats	OK
SSE /chat when engine running	OK (~19 s)
/update — praisonaiagents 1.7.1 current	OK
Engine portability tests in shipped tree	41/42 pass (1 dev-only: missing Rust sources in bundle)

This issue is supervisor / first-run / UX — not engine HTTP implementation.

Related (same release QA)

Topic	Relation
Silent exit without AppData	Worse startup — no window
ProductVersion 0.1.0 vs 4.7.3	Same binary, metadata bug
v4.7.3 release notes	Windows desktop + Training tab

Labels (suggested)

• bug, desktop, windows, engine, first-run, ux

[praisonai-triage-agent]

👋 Thanks for opening this issue, @Dhivya-Bharathy!

A maintainer will review this shortly. In the meantime:

• Make sure you've included steps to reproduce (for bugs)
• Check existing issues for duplicates
• Review the documentation for related guides

Bug and enhancement reports are auto-triaged with Claude. Questions and other issues: a maintainer can comment @claude to trigger analysis.

Routing: Agent-callable tools → PraisonAI-Tools; lifecycle plugins (tracing/hooks/guardrails) → PraisonAI-Plugins. TypeScript/JavaScript SDK fixes land in src/praisonai-ts/ in this repo.

[praisonai-triage-agent]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[dajiaohuang]

I can take this. The active Train tab in the report exposes a reproducible UI-state race: while boot() awaits engine_status, the saved Train view is restored; the first-run setup is then rendered in the hidden Chat view. I'll submit a focused fix that keeps engine-dependent views from replacing setup until the engine is ready, with a regression test.

[praisonai-triage-agent]

Claude encountered an error —— View job

---

Analyzing issue #4441 — Desktop engine never starts on Windows

• Read AGENTS.md and desktop architecture guidelines
• Investigate the UI-state race (@dajiaohuang's hypothesis: saved Train view restored, setup rendered in hidden view)
• Locate boot()/engine_status handling in praisonai-desktop frontend
• Implement minimal fix
• Add regression test
• Commit, push, create PR

[praisonai-triage-agent]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[praisonai-triage-agent]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.