Comfy-Org / Comfy-Org/ComfyUI_frontend

Capture and alert on boot-path errors before Sentry initializes (white-screen blind spot)

Open
#14,036 1 comment 1 reaction 0 assignees View on GitHub
area:i18n enhancement
Dominant language
TypeScript
Stars
2k
Forks
699
Avg merge
1d 7h
Merged PRs (30d)
490

Description

## Problem

A boot-path failure **before the app mounts** currently escapes our error monitoring. In the 1.47 cycle the i18n `nodeDefs` crash white-screened **staging** and forced a rotation rollback — it was caught by manual QA, not by an alert.

Root cause of the blind spot is initialization order:

- `index.html` loads `src/bootstrap.ts` as a module.
- `bootstrap.ts` runs `initDatadogRum()` (cloud only) and then `await import('./main')`.
- `src/main.ts` statically imports `@/i18n` (which **eagerly** imports `locales/en/nodeDefs.json`), performs a top-level `await refreshRemoteConfig()`, and **only then** calls `Sentry.init(...)`.

So any throw during `main.ts` module-evaluation or the pre-`init` awaits — exactly the i18n `nodeDefs` class of failure — happens **before Sentry exists** and is never captured by Sentry.

Compounding the user-facing symptom: the splash loader is removed only in `App.vue`'s `onMounted` (`src/App.vue:31`). If the app never mounts, the splash stays up forever — the "white/stuck screen" with nothing surfaced to the user.

## What already exists (audited on `origin/main`)

- **Sentry** (`@sentry/vue`) is initialized in `src/main.ts`; its default browser integration does capture `window.onerror` + `unhandledrejection`, **but only after `Sentry.init` runs**. Source maps upload to staging + prod Sentry projects.
- **Datadog RUM** is initialized in `bootstrap.ts` *before* the `main` import — but it is **cloud-only** (keyed on `*.comfy.org` hostnames) and RUM error ingestion is **not an alert/page**. Desktop and self-hosted web have **no** early net at all.
- There is **no** early `window.onerror` / `unhandledrejection` handler in `index.html` or `bootstrap.ts`.

## Proposal

1. Add a tiny **early global error trap** — an inline `` in `index.html` (or the very top of `bootstrap.ts`, before the `main` import) that installs `window.onerror` + `unhandledrejection` listeners and **buffers** captured errors.
2. When `Sentry.init` completes in `main.ts`, **flush** the buffered boot errors into Sentry (`captureException`) so the pre-init window is no longer blind, on every distribution (cloud/desktop/web), not just cloud.
3. Add a **boot-failure fallback UI**: if the app has not mounted within a timeout (or a boot error was trapped), replace the stuck splash with a minimal "failed to load" message instead of an indefinite splash.
4. Ensure a **Sentry alert rule** exists for boot-path errors (tag boot errors, e.g. `phase: boot`) so a staging/prod white-screen pages someone instead of waiting for manual QA. (Alert config lives in the Sentry dashboard — call it out explicitly in the acceptance criteria so it isn't forgotten.)

## Acceptance criteria

- [ ] An error thrown during `main.ts` module-eval / pre-`Sentry.init` awaits is captured by Sentry on cloud, desktop, and self-hosted web.
- [ ] Boot errors are tagged (e.g. `phase: boot`) so they are filterable and alertable.
- [ ] A boot-path Sentry alert rule is configured to notify (Slack/page) on staging + prod.
- [ ] A boot failure surfaces a fallback UI to the user instead of an indefinite splash.
- [ ] A regression test simulates a boot-path throw (e.g. locale-load failure) and asserts the error reaches the capture path.

## Motivating incident

The i18n `nodeDefs` boot crash that white-screened staging and forced a rotation rollback in the 1.47 cycle.

Contributor guide

Open the contributing guide

Research direction

Read index.html, src/bootstrap.ts, src/main.ts, and src/App.vue to trace boot errors, Sentry initialization, and splash removal. Add regression coverage for a module-evaluation or locale-load failure and verify the error reaches Sentry with a boot tag. Done means early errors are captured across distributions, the fallback UI appears, and staging and production alert rules are configured.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend, observability, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.