unity-safe-mode-recovery

Imported from Rigaro/Agent-Skills (skills/unity-safe-mode-recovery/SKILL.md). Install upstream with npx skills add Rigaro/Agent-Skills --skill unity-safe-mode-recovery. Copyright stays with the author (Unlicense).

Unity Safe Mode and stuck editor recovery

Detect

unity status --json --no-banner            # connected editors with the pipeline package
unity pipeline list --json --no-banner     # isRunning, hasPipelinePackage, safeMode, reachable server

• safeMode: true: the last compilation failed; scripts are not loaded; every MCP tool that lives in an editor assembly is gone.
• isRunning: true but isReachable: false: the editor is compiling, importing, or the pipeline package is not resolved yet (focus the editor so it imports the manifest).
• No instance at all: the editor is closed, or a different project is open.

Read the errors (never the whole log)

Select-String -Path "$env:LOCALAPPDATA\Unity\Editor\Editor.log" -Pattern "error CS" | Select-Object -Last 20

macOS: grep "error CS" ~/Library/Logs/Unity/Editor.log | tail -20. Batch runs: the log path passed with -logFile or printed by the CLI.

Each line has Assets/.../File.cs(line,col): error CSxxxx: message. Fix them all; one remaining error keeps the editor in Safe Mode.

Fix and recover

1. Edit the C# (the editor watches the files and recompiles when focused; in Safe Mode press "Exit Safe Mode" after the compile succeeds, or let it exit automatically).
2. Confirm: unity pipeline list shows safeMode: false and a reachable server; the console tool reports no errors.
3. MCP bridges that do not reconnect within a minute: restart the editor (unity open or the Hub), then re-approve the MCP client connection if the project asks.
4. A never-ending domain reload or import: look for exceptions in [InitializeOnLoad], asset postprocessors or custom importers in the console; remove the offending change; as the last resort close the editor from the OS and report it, since unsaved scene changes are lost.
5. Headless verification without touching the open editor: unity test <project> --mode EditMode (needs the project closed) compiles everything and reports the same errors.

Prevent

• Compile-check after every C# edit before moving on.
• Keep editor-only code under an Editor folder or an editor assembly definition.
• Never write to Assets/ while a batch editor is starting (it imports what it finds).