> ## 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.
# Boot Failures
> What each BootResult.reason renders on the crash screen, and when it fires
This page is about failures reported by `createApp`, i.e. after `app.js` has parsed and run. For the one failure mode where the bundle itself cannot load โ and for what a user sees on a slow cold start โ see [Boot Indicator](/docs/features/mobile/boot-indicator).
`createApp` returns a typed `BootResult`. A **permanent** failure is a named `{ ok: false, reason, detail }`, and `mount()` renders it on the crash screen. A **retryable** unreadiness no longer stops boot: the app starts, and the success branch carries a `notReady` field so the caller can say the engine is not answering yet. A *thrown* failure is still caught and named too.
```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { createApp, type BootResult } from "praisonai-mobile/app/boot";
const booted: BootResult = await createApp(deps);
if (!booted.ok) {
renderFatal(root, strings.bootFailed(booted.detail)); // permanent failure
} else if (booted.notReady) {
render(strings.engineNotReady(booted.notReady.detail)); // booted, but warn
}
```
Only a permanent unreadiness (`version_mismatch`) reaches the failure branch. A retryable unreadiness โ a still-starting engine, an unreachable phone-to-desktop socket โ is delivered as a *usable app plus an attached warning*, not a refusal.
```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export type BootResult =
| {
readonly ok: true;
readonly app: App;
/** The app started, but the engine is not answering yet. A caller must
* SAY so -- silently booting into an engine that cannot reply is how a
* first message fails with no explanation. */
readonly notReady?: { readonly reason: string; readonly detail: string };
}
| {
readonly ok: false;
readonly reason: string;
readonly detail: string;
/** Set when the failure is a health probe that might succeed on a retry.
* In normal flow this is effectively always unset now -- retryable
* outcomes take the SUCCESS branch with `notReady` instead. */
readonly retryable?: boolean;
};
```
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Create[๐ญ createApp] --> Ok{ok?}
Ok -->|"true, no notReady"| Mount[๐ผ๏ธ mount clean]
Ok -->|"true, notReady set"| Warn[โ ๏ธ mount + warning notice]
Ok -->|false| Fatal[๐ฅ crash screen]
Throw[๐ฃ throw] --> BootOrFail[๐ก๏ธ bootOrFail]
BootOrFail --> Fatal
classDef create fill:#8B0000,stroke:#7C90A0,color:#fff
classDef branch fill:#189AB4,stroke:#7C90A0,color:#fff
classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef fail fill:#8B0000,stroke:#7C90A0,color:#fff
class Create create
class Ok branch
class Mount ok
class Warn warn
class Throw,BootOrFail warn
class Fatal fail
```
## Quick Start
`mount()` checks `booted.ok` and renders the crash screen with the detail. There is nothing to configure โ a named failure always reaches the screen.
```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
if (!booted.ok) {
renderFatal(root, strings.bootFailed(booted.detail));
return null;
}
```
A retryable unreadiness โ a still-starting engine, an unreachable remote โ no longer reaches the `!booted.ok` branch. The app booted; `booted.notReady` carries the reason so you can say so. Sending later retries it.
```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
if (booted.ok && booted.notReady) {
// The app is up. Say the engine is not ready; sending will retry.
render(strings.engineNotReady(booted.notReady.detail));
}
```
A `version_mismatch` โ a build that cannot speak the server's protocol โ never fixes itself on a retry, so it stays on the failure branch and reaches the crash screen.
```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
if (!booted.ok && booted.reason === "version_mismatch") {
renderFatal(root, strings.bootFailed(booted.detail)); // waiting cannot help
}
```
`bootOrFail` wraps `createApp` so an unanticipated throw โ a `StoragePort` failure at `settingsStore.load()` โ becomes the same typed shape rather than an uncaught rejection.
```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
try {
return await createApp(options);
} catch (error) {
return { ok: false, reason: "storage_unavailable", detail: String(error) };
}
```
***
## What the crash screen guarantees
The fatal screen carries three properties, each pinned by a test.
* **It announces.** The fatal element is `role="alert"`, not `role="status"`, so a screen reader speaks it the moment it mounts.
* **It names the real failure.** The message is `booted.detail`, the actual failure detail โ never a generic "something went wrong".
* **It replaces the chrome.** `root.textContent = ""` runs first, so the dead app UI is gone; the fatal element is not appended under the corpse of the send button.
***
## Where each reason surfaces
Probe reasons split by whether a retry can help. Permanent ones refuse boot; retryable ones boot the app and attach `notReady`.
### Permanent boot failures โ surface via `!booted.ok`
| `reason` | Source | When it fires |
| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `unknown_engine` | `selectEngine` โ no engine with that id, or an engine reporting a different id than it registered under | A settings `engineId` naming an engine that is not built |
| `protocol_mismatch` | `selectEngine` โ the engine speaks a different `PROTOCOL_VERSION` than this build | An engine adapter upgraded out of step with the app |
| `storage_unavailable` | `bootOrFail` โ a throw from `createApp`, caught and named | `SecurityError` (site data blocked) or `QuotaExceededError` at `settingsStore.load()` |
| `version_mismatch` | `selectEngine` โ probe response reported a `version` this build cannot speak | Server upgraded incompatibly โ waiting cannot fix it |
### Retryable unreadiness โ surface via `booted.ok === true` with `booted.notReady`
| `booted.notReady.reason` | Source | When it fires |
| ------------------------ | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `unhealthy` | `selectEngine` โ probe classified a `200 {"ok": false}` response | Remote engine is up but reporting itself not ready (still binding, dependency down) |
| `http_status` | `selectEngine` โ probe got a non-200 (including 404, 5xx, and any sub-200) | Wrong `baseUrl`, endpoint not routed, proxy misconfigured |
| `malformed` | `selectEngine` โ probe reached something whose body is not our engine's shape | A captive portal, a proxy error page, a different service on the port |
| `transport` | `selectEngine` โ probe request or body read threw, aborted, or timed out after `PROBE_TIMEOUT_MS` (5s) | Engine unreachable, still binding its socket, or a hanging endpoint / black-hole proxy |
`retryable` on the failure branch is now effectively always `false` (or unset), because retryable outcomes take the **success** branch with `notReady`. `unknown_engine` and `protocol_mismatch` are the two failures `selectEngine` *anticipates* without any I/O; `version_mismatch` is the one probe reason still permanent. `storage_unavailable` is different in kind: it is a **throw** the boot never expected, turned into the same shape by `bootOrFail` so it renders the same way.
***
## Boot-time health probe
When an `EngineChoice` supplies a `probe`, `selectEngine` runs it *after* the cheap protocol check. A **retryable** probe result flows into the success branch with `notReady` and the engine is **kept**; only a **permanent** probe result flows into failure and disposes the engine.
The probe reasons split on whether a retry can help. `unhealthy`, `http_status`, `malformed`, and `transport` all carry `retryable: true` โ the engine is still handed to the app so a retry costs one tap, and the app renders a warning. Only `version_mismatch` is permanent and refuses boot with the engine disposed.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Start[๐ญ selectEngine] --> Known{๐ id known?}
Known -->|No| Unknown[โ unknown_engine]
Known -->|Yes| Proto{๐ protocol matches?}
Proto -->|No| Mismatch[โ protocol_mismatch]
Proto -->|Yes| HasProbe{๐ probe supplied?}
HasProbe -->|No| Ok[โ
engine offered]
HasProbe -->|Yes| Ready{๐ probe ready?}
Ready -->|Yes| Ok
Ready -->|"No, retryable"| Attach[โ ๏ธ ok:true + notReady โ engine KEPT]
Ready -->|"No, permanent"| Refused[โ version_mismatch]
Refused --> Dispose[๐งน engine.dispose #40;no leaked socket#41;]
classDef start fill:#8B0000,stroke:#7C90A0,color:#fff
classDef branch fill:#189AB4,stroke:#7C90A0,color:#fff
classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef fail fill:#8B0000,stroke:#7C90A0,color:#fff
classDef clean fill:#6366F1,stroke:#7C90A0,color:#fff
class Start start
class Known,Proto,HasProbe,Ready branch
class Ok ok
class Attach warn
class Unknown,Mismatch,Refused fail
class Dispose clean
```
A **permanently** refused probe (`version_mismatch`) disposes the engine before returning, exactly as a protocol mismatch does โ the probe opened a socket, and leaving the engine holding it is a leak. A **retryably** refused probe **keeps** the engine, because it is the one the app will use once the remote comes up; disposing it would leave the app holding a dead engine it can never retry through.
***
## An unreachable engine boots with a warning
Before PR #4672 a missing `/health` handler took the whole app down; now the app opens and points the user at Settings.
```
before: no /health handler โ "PraisonAI could not start: 404" (dead app, no way in)
after: no /health handler โ App opens; a warning row says the engine is not
answering yet; the user can reach Settings.
```
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant App as Mobile App
participant Probe as Health Probe
participant Engine
User->>App: Launch app
App->>Probe: probeHealth(baseUrl)
Probe--xEngine: (unreachable)
Probe-->>App: { ready: false, reason: "transport", retryable: true }
App->>App: mount() + render "engine not answering" notice
App-->>User: App opens with warning banner
User->>App: Open Settings, fix baseUrl
User->>App: Type message, tap Send
App->>Engine: retry with new baseUrl
Engine-->>App: streams answer
App-->>User: answer in transcript
```
***
## How a throw becomes a typed failure
`createApp` calls `settingsStore.load()` without a guard, so a `StoragePort` failure propagates as an exception. The chrome is already appended by the time boot runs, so an unhandled rejection would skip both the crash screen and the listener registrations โ leaving a fully rendered app in which nothing happened. `bootOrFail` closes that gap.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant Mount as mount
participant BootOrFail as bootOrFail
participant Create as createApp
Mount->>BootOrFail: bootOrFail(options)
BootOrFail->>Create: createApp(options)
Create--xBootOrFail: throw (StoragePort failed)
BootOrFail-->>Mount: { ok: false, reason: "storage_unavailable", detail }
Mount->>Mount: renderFatal(detail)
```
The crash handler is installed in `mount()` **before** `detectPlatform()`, because `detectPlatform` reads `window.localStorage` and can itself throw `SecurityError`. See [Architecture โ Boot Order](/docs/features/mobile/architecture#boot-order) for the full ordering.
***
## Related
The pre-boot frame and the failure notice for a bundle that cannot load.
Boot order and where the crash handler is installed.
When the `StoragePort` is unavailable at boot.
Failures that happen inside a turn, not at boot.
Where `unknown_engine` and `protocol_mismatch` come from.
How the probe classifies a `/health` response into the reasons above.