> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Engine, Updates & Diagnostics

> Read the startup pill, view engine logs, and fix common failures

The startup pill and engine log tell you exactly what the local engine is doing, and every failure attaches the engine's own output.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# If this agent's engine can't start, the pill shows why.
agent.start("Are you there?")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Start[⏳ starting engine] --> Ready[✅ engine :PORT]
    Start --> Failed[🛑 engine failed]
    Failed --> Log[📜 Engine Log]

    classDef start fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ready fill:#10B981,stroke:#7C90A0,color:#fff
    classDef failed fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef log fill:#6366F1,stroke:#7C90A0,color:#fff

    class Start start
    class Ready ready
    class Failed failed
    class Log log
```

## Quick Start

<Steps>
  <Step title="Read the startup pill">
    The pill shows `starting engine`, then `engine :PORT` on success or `engine failed` with a tail on failure.
  </Step>

  <Step title="Open the engine log">
    The log viewer shows the engine's recent activity — a bounded 400-line ring buffer — without leaving the app.
  </Step>

  <Step title="Reset the engine if it's stuck">
    Close the app, delete the lockfile in the data directory, and relaunch.
  </Step>
</Steps>

***

## Startup States

| Pill              | Meaning                                                          |
| ----------------- | ---------------------------------------------------------------- |
| `starting engine` | The shell is spawning Python                                     |
| `engine :PORT`    | The engine is listening and passed the `/health` probe           |
| `engine failed`   | Startup failed — the last lines of the engine's output are shown |

On failure, the tail comes from the supervisor's 12-line buffer, so you see the actual error rather than a bare exit code.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Shell as 🖥️ Shell
    participant Py as 🧠 Engine

    Shell->>Py: spawn (30s deadline)
    alt announces + health ok
        Py-->>Shell: engine :PORT
    else dies or times out
        Py-->>Shell: engine failed (tail)
    end
```

***

## Common Failures

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    cd src/praisonai-agents
    .venv/bin/pip install praisonaiagents
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## 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".

<Note>
  `check_updates` can be on, but until a release feed is configured the check will honestly report that it is not set up.
</Note>

***

## Reset Recipe

<Steps>
  <Step title="Quit the app">
    Fully close the window so the engine process exits.
  </Step>

  <Step title="Delete the lockfile">
    Remove the lockfile in `~/Library/Application Support/PraisonAI`.
  </Step>

  <Step title="Relaunch">
    Reopen the app — the shell spawns a fresh engine and the pill returns to `starting engine`.
  </Step>
</Steps>

***

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Keep one PraisonAI process at a time">
    "Address in use" comes from a second process on the port. Close extras before relaunching.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Overview" icon="display" href="/docs/features/desktop/index">
    Install, launch, and how the engine starts
  </Card>

  <Card title="Data & Privacy" icon="lock" href="/docs/features/desktop/data">
    Where the data directory and lockfile live
  </Card>
</CardGroup>