Troubleshooting Installation

Run calmui doctor first

Before working through the sections below, run calmui doctor [--project <uproject dir>] (or Diagnose from Studio's Unreal dashboard or command palette). It checks:

• versions: CLI fingerprint vs. Studio's reported version: build Studio (pnpm --dir apps/studio studio:build) or set CALMUI_STUDIO_EXECUTABLE.
• wasm-fingerprint: WASM manifest fingerprint vs. the CLI: rebuild the WASM core (pnpm --dir apps/studio build:wasm).
• studio-debug-vite: a debug Studio build's Vite dev server at 127.0.0.1:1420: start it with pnpm --dir apps/studio dev.
• msvc-toolset: configured build dirs agree on an MSVC toolset: reconfigure the mismatched or unreadable build dir.
• dev-server-json: .calmui/dev-server.json points at a live, single calmui dev daemon: delete a stale file and restart, or shut down an extra daemon with calmui dev shutdown.
• plugin-drift: the project's staged plugin headers match the workspace: restage the plugin copy (calmui support bundle or a project resync).
• disk-free: at least 10 GiB free on the drive holding build/: free disk space (see the disk hygiene notes in docs/architecture/subsystems/studio.md).
• input-mode: DefaultGame.ini sets bApplyHostInputMode explicitly when Enhanced Input is enabled: set it under [/Script/CalmUI.CalmUiProjectSettings] in DefaultGame.ini.

Plugin missing

Close Unreal and check that <Game>/Plugins/CalmUI/CalmUI.uplugin exists. Install again from Studio if the folder is absent.

Unreal reports duplicate CalmUI plugins

Close Unreal and run Install or Update Plugin again from Studio. Current Studio builds preserve replaced copies in <Game>/Saved/CalmUI/PluginBackups and move misplaced CalmUI backup copies out of the folder Unreal scans for plugins. After the repair, the only CalmUI descriptor below <Game>/Plugins should be Plugins/CalmUI/CalmUI.uplugin.

Wrong Unreal version

This release is validated with Unreal Engine 5.7.4. Use that version before reporting a build problem.

Studio cannot find its compiler

Reinstall the complete Studio artifact. The matching compiler is bundled; a global PATH entry is not required.

Package is stale or incompatible

Save the source in Studio and rebuild the package. If the message shows a package version outside 1.0-1.12, update Studio and the plugin together.

Project plugin is newer than Studio's copy

Studio protects project plugin files from replacement when their modification times are newer than its bundled copy. A local Unreal rebuild can also trigger this check; it is not proof of a newer source version. Keep the project plugin unless you intend to replace it. Repository developers can run pnpm studio:build to rebuild Studio together with its bundled compiler and Unreal plugin.

Content overlaps a cutout or TV edge

CalmUI does not insert safe padding automatically. Add the env(calmui-safe-area-inset-*) values to the relevant source layout and verify it with Studio Preview's Safe area selector. If Unreal and Studio differ, check the active Unreal UI DPI scale: Unreal converts its platform-reported physical safe zone to logical CalmUI pixels.

More help

Use Help → Open logs folder and Help → Create support bundle. The bundle contains versions and sanitized configuration, not source files, assets, environment variables, or secrets.