# Safe mode Source: https://docs.ideharmony.com/troubleshooting/safe-mode Safe mode starts Harmony without loading optional extension code. It exists for one situation: something you installed prevents the app from starting or working, and you need to get in to remove it. > [!IMPORTANT] > Reach for safe mode **before** deleting configuration. Deleting your config > takes your settings, profiles, layouts, and workspace definitions with it, and > it usually was not the problem. Safe mode exists so that step is unnecessary. ## When to use it | Symptom | Safe mode helps? | |---|---| | App will not start after installing an extension | **Yes** | | App starts, then becomes unresponsive | **Yes** | | Everything slowed down after an install | **Yes** — isolates it | | A skill will not load | Sometimes — confirms whether it is extension-related | | Daemon unreachable | No — see [daemon problems](/docs/troubleshooting/daemon) | | Provider will not authenticate | No — see [authentication](/docs/troubleshooting/authentication) | Safe mode isolates **extension code**. It does not fix transport, credentials, or packaging problems, and using it for those wastes time. ## What it does not disable Safe mode is narrower than people expect: | Still active | Why | |---|---| | The daemon | It is the product, not an extension | | Your sessions, tasks, artifacts | Durable state is untouched | | Your workspaces | Configuration is read, not executed | | Provider CLIs you launch | Separate processes | > Safe mode is not a factory reset. **Nothing is deleted.** It changes what gets > loaded at startup, and that is all. ## The isolation loop 1. Start in safe mode. 2. Confirm the problem is gone. If it is not, the cause is not an extension — stop here and look elsewhere. 3. Restart normally with **one** extension enabled. 4. Repeat until the problem returns. 5. The last one you enabled is the cause. Reintroducing one at a time is slower and it is the only approach that identifies the culprit rather than making the symptom disappear for unclear reasons. > [!TIP] > Note what you disabled as you go. Three restarts in, "which ones have I > already ruled out" becomes a real question. ## Once you have found it - **Remove it** through the surface that installed it, not by hand-editing. Hand-removal leaves Harmony believing it is still registered. - **Verify** with `harmony doctor`. - **Report it** if a single extension could crash the whole app — that is a defect. Include the extension, its version, and redacted `harmony doctor --json`. ## If safe mode does not help The problem is not extension code. Work through, in order: 1. [Daemon problems](/docs/troubleshooting/daemon) — transport and instance isolation. 2. [Installation problems](/docs/troubleshooting/installation) — a broken or partial install. 3. [Performance problems](/docs/troubleshooting/performance) — load rather than failure. ```powershell harmony doctor --json ``` > [!WARNING] > Review diagnostics before sharing. They contain absolute paths, workspace and > repository names, and provider details. ## Why this exists at all Extension code is **not sandboxed**. It runs with the privileges of the process that loads it. A failing extension should degrade only its own feature, but "should" is not "will" — safe mode is the guaranteed way back in when it does not. That is also the argument for installing deliberately in the first place. See [customization](/docs/customization). ## Related - [Extension problems](/docs/troubleshooting/extensions) - [Hooks](/docs/customization/hooks) - [Security overview](/docs/security)