Skip to content

docs(desktop): document instance launch, stop, and crash recovery - #1873

Closed
lin-bot23 wants to merge 3 commits into
Comfy-Org:mainfrom
lin-bot23:desktop-docs-1004
Closed

lin-bot23 wants to merge 3 commits into
Comfy-Org:mainfrom
lin-bot23:desktop-docs-1004

Conversation

@lin-bot23

@lin-bot23 lin-bot23 commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

What

Documents the instance lifecycle in Comfy Desktop, which had no coverage: a new Launching, Stopping, and Restarting an Instance section on the Instance Management page.

  • Launching: click an instance card in the Chooser. The window shows the startup progress, then the ComfyUI interface once the server is ready.
  • Launching while another instance is running: the An instance is already running dialog lists the instances it would stop. Close & Launch stops the listed instances first; Run All launches the new instance alongside them. Restarting an instance never prompts. The dialog can be turned off with Warn before running multiple instances in Desktop Settings → Preferences.
  • Stopping: Stop from the instance card's ⋮ menu stops the server and keeps the window open on a ComfyUI is stopped card with Relaunch ComfyUI and Return to Dashboard.
  • Crash recovery: ComfyUI could not start and ComfyUI exited unexpectedly cards, showing the exit code or signal when Comfy Desktop can read it and, on Windows, a memory access violation with a missing Microsoft Visual C++ Redistributable hint. Actions: Restart ComfyUI and Back.

Sources

  • src/renderer/src/composables/useLocalInstanceGuard.ts in Comfy-Org/Comfy-Desktop: the multi-instance warning, its buttons, and the warnBeforeRunningMultipleInstances preference
  • src/renderer/src/panel/ComfyLifecycleView.vue: the stopped and crashed cards and their actions
  • locales/en.json (launch.instanceRunning*, comfyLifecycle.*, settings.warnBeforeRunningMultipleInstances)

Localization

All four languages are updated in this PR: EN, zh, ja, ko, including the frontmatter hashes (translate:sync-hash run for this page only).

The ja page also picks up one small fix: the placeholder in the Python environment example is now the byte-identical <ComfyUI_dir> instead of a localized variant, matching the English source.

Checklist

  • Only installation/desktop/usage/instance-management.mdx and its zh/ja/ko counterparts are touched. No nav change needed (existing page).
  • check-anchors clean for the four files; structure parity and content parity clean for the page.
  • Links resolve inside each locale (settings page anchor uses the localized heading slug).

Added in a follow-up commit: the asset database failure

ComfyUI turns its assets system on by default and now names the reason when it cannot open its asset database (ASSETS_STARTUP_FAILED: <kind>, then a message, then exit 1). The crash section now covers what the user sees instead of "Process exited with code 1":

  • Another ComfyUI already using this installation's database: Comfy Desktop's own copy, with the two ways out (close the other ComfyUI or the app that started it, or give one of them its own database location with the --database-url startup argument).
  • The other kinds (locked by another program, written by a newer ComfyUI, impossible to create in that folder, corrupt): ComfyUI's own message, which names the database file and the fix and ends with the option to start the instance without the asset system via --disable-assets.

Sources: src/main/lib/assetsStartupFailure.ts, the failure path in src/main/lib/ipc/sessionActions/launch.ts, the exact user-visible text asserted by e2e/assets-startup-failure.test.ts, and ComfyUI's main.py (stop_startup() / database_failure_message()). Upstream: Comfy-Org/Comfy-Desktop#1688.

@coderabbitai

coderabbitai Bot commented Oct 4, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: a73da4ab-881c-4032-a608-60d513acb1f1
📥 Commits

Reviewing files that changed from the base of the PR and between d59d148 and c094cd4.

📒 Files selected for processing: 4
  • installation/desktop/usage/instance-management.mdx
  • ja/installation/desktop/usage/instance-management.mdx
  • ko/installation/desktop/usage/instance-management.mdx
  • zh/installation/desktop/usage/instance-management.mdx

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

📝 Walkthrough

The desktop instance-management guides now describe launching, stopping, and restarting instances. They cover launch-conflict choices, stopped and error states, recovery actions, Windows crash details, and asset-database errors. Japanese, Korean, and Chinese guides include translated content and updated translation metadata.

Changes: Instance lifecycle documentation

Layer / File(s) Summary
Document instance lifecycle behavior
installation/desktop/usage/instance-management.mdx, ja/installation/desktop/usage/instance-management.mdx, ko/installation/desktop/usage/instance-management.mdx, zh/installation/desktop/usage/instance-management.mdx
The English guide describes launch choices, stopping and restarting, failure states, and asset-database errors. The Japanese, Korean, and Chinese guides add translated guidance and translation metadata.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to c094c

The documentation is mergeable based on the available evidence.

### Architecture Summary

Architecture risk: 🔵 Low · up to c094c

The change affects 4 systems.

Changed systems: installation, ja, ko, zh

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — installation (service) was modified; 1 changed file maps to changed impact.
  • observed — ja (service) was modified; 1 changed file maps to changed impact.
  • observed — ko (service) was modified; 1 changed file maps to changed impact.
  • observed — zh (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in installation/desktop/usage/instance-management.mdx: Added guidance for launching an instance, including startup progress and the ready interface. When a local instance is launched while another local instance is running or starting, the dialog lists the instances it would stop; Close & Launch stops them before launching the selected instance, Run All launches alongside them, and dismissal cancels. Restarting bypasses the dialog, and a Desktop Settings preference disables the warning. Stopping leaves the window open with options to relaunch ComfyUI or return to the Dashboard.
  • observed — Modified behavior in installation/desktop/usage/instance-management.mdx: Added descriptions of startup failure and unexpected-exit cards, including an exit code or terminating signal when available. Windows crash details may mention a memory access violation and missing Visual C++ Redistributable files; the card provides logs, restart, and return options.
  • observed — Modified behavior in installation/desktop/usage/instance-management.mdx: Added asset-database failure guidance: when another ComfyUI is using the installation’s database, close that process or assign a separate database location with --database-url. For other database failures, the message identifies the file and fix and offers starting without the asset system using --disable-assets.
  • observed — Modified behavior in ja/installation/desktop/usage/instance-management.mdx: 翻訳ソースハッシュを更新し、起動・停止・再起動の翻訳ブロックハッシュを追加しました。
Pre-merge checks: Passed 2
Passed Passed checks: 2 passed
Check name Status Explanation
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
✨ Simplify code
  • Create a new PR
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

lin-bot23 and others added 3 commits October 14, 2026 14:44
Add a Launching, Stopping, and Restarting an Instance section to the
Instance Management page: how launching works, the multi-instance
warning (Close & Launch / Run All) and its preference, the stopped
card with Relaunch ComfyUI, and the crash card with Restart ComfyUI.

Sources: src/renderer/src/composables/useLocalInstanceGuard.ts,
src/renderer/src/panel/ComfyLifecycleView.vue, locales/en.json
(launch.instanceRunning*, comfyLifecycle.*).

Also fixes a pre-existing ja drift: the identifier in the Python
environment example is now the byte-identical <ComfyUI_dir>.
@comfyui-wiki

Copy link
Copy Markdown
Member

Superseded by #1961: consolidated Desktop docs (first-run, migration, title bar, performance tests, settings/beta, instance launch/stop/crash, update-check FAQ, Ollama FAQ).

@comfyui-wiki

Copy link
Copy Markdown
Member

Closing in favor of #1961 (Desktop consolidation). Content preserved there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants