---
title: Debugging and troubleshooting
description: Revision-aware DevTools behavior and practical failure diagnosis.
status: approved
visibility: public
sourceRevision: e7ab5dcc0069ade3393cc0e033e4541a78eaae3b
reviewedAt: 2026-09-22
---

# Debugging and troubleshooting

First record the host commit, plugin commit, `.uproject`, engine version and launch flags. `0.57.0-dev` alone cannot distinguish the known-broken baseline inspector from the repair candidate. See [version notes](https://betterbuilt.games/docs/quartz-ui/versions).

## Baseline: rendering works, native inspector does not

At published host `91fd772c282098157c4e7cded0263844f076e9fb` / plugin `933db5171161ac5966e3b9bca3fd3a965f5399cc`, **Tools > Quartz UI > Open DevTools** opens a target-specific inspector, but CEF rejects the browser WebSocket Origin `http://127.0.0.1:9222`. Elements and Console remain empty/disconnected. Earlier independent baseline testing reproduced this failure. A separate direct protocol read proved the live page existed; it did not make the native menu pass.

Treat this as the known baseline defect. Do not add wildcard Origin flags, strip Origin headers or expose the debugging port. The baseline quickstart's success is visible rendering plus bridge/app readiness, not inspection.

## Candidate: one-click live inspection, with remaining review limits

Plugin `e7ab5dcc0069ade3393cc0e033e4541a78eaae3b` is a repair candidate that invokes Chrome's native remote Inspect action for the exact live target. It adds a Node launcher and version-sensitive Chrome adapter. Node **22+** and a compatible Chrome are required; independent evidence used Node `22.23.2` and Chrome `153.0.8010.53` with UE's bundled CEF `128.0.6613.138`. Edge discovery exists in source but Edge and other Chrome versions have not been validated.

When an authorized candidate checkout is ready:

1. Start PIE and wait for the live reference UI.
2. Release mouse capture when needed, then use **Tools > Quartz UI > Open DevTools**. One page opens directly. Multiple pages use an Editor title/URL picker.
3. Confirm Elements is populated and Console can evaluate `document.URL`, expecting `https://reference.quartzui.test/index.html` for the host fixture.
4. Arm the element selector and click SERVERS or SHOP in the Unreal viewport. The corresponding DOM node should be selected **without** navigating the app. After inspection ends, ordinary clicks should navigate again.
5. Verify preview selection separately, then close/reopen the inspector and stop/restart PIE to check cleanup and target replacement.

Independent candidate QA passed the two viewport reproductions, ordinary-click restoration, preview selection and lifecycle. The physical captured-mouse **Shift+F1** hardware-input step remains unverified; synthetic key delivery reached an Editor shortcut and is not proof that human input is broken. Multi-page picker evidence is from prior candidate `acfea46445f8400e19181d580df9c9844ec6cd84`, not a repeated `e7ab5dcc` test. This evidence does not establish a released fix or an updated reference-host pin.

The preview contains the **Chromium UI document**, not the Unreal world or desktop. Candidate QA observed lossless PNG at 939 x 376 after panel resizing and 210 delivered frames in five seconds with the inspector focused. This is a measured fixture result, not a resolution or frame-rate guarantee. The candidate temporarily exempts the Editor from background CPU throttling while its live inspector is active and restores normal behavior on close/PIE teardown; it does not change the global preference.

## Settings and logs

Project policy lives under **Project Settings > Plugins > QuartzUI**; machine tooling lives under **Editor Preferences > Plugins > QuartzUI**. The project must permit Editor DevTools. Restart the Editor after a debug port/startup-option change because CEF is already initialized. Candidate settings include **Node Executable** and optional **Inspector Browser Executable**. Missing tools produce a bounded failure; nothing is installed automatically.

The candidate uses an isolated profile under `Saved/QuartzUI/DevTools/<editor-pid>/BrowserProfile`. Close its windows normally. Launcher output uses `LogQuartzUIEditor`; inspect the host's Editor log and `cef3.log` as well. The browser may remain open after Editor exit; do not terminate unrelated Chrome sessions. The Editor module and its automatic debug setup do not run in packaged game executables.

## Diagnose the first failing boundary

| Symptom | Check and next step |
| --- | --- |
| Private clone or submodule authentication fails | Confirm authorized access to host and plugin separately through local login. Use the repository URLs supplied with preview access. |
| App asset is a text file beginning with an LFS pointer | Hydrate Git LFS in an agreed baseline checkout; verify the hash in [installation](https://betterbuilt.games/docs/quartz-ui/installation). |
| Plugin missing or Editor module mismatch | Inspect actual submodule SHA and `QuartzUI.uplugin`; build the correct host Editor target with the exact engine. Preserve caches. |
| Build cannot locate a compiler/SDK | Check VS C++ tools and Windows SDK; the tested versions are environment evidence, not a substitute for provisioning. |
| `npm.ps1` is blocked by PowerShell execution policy | For an existing Node installation use `npm.cmd` for npm commands. Do not change machine policy to inspect its version. |
| No reference UI after Play | Check Default App, Automatic startup, hydrated app asset, Entry map, output files and initial shader progress. Look for stable QuartzUI failure codes before recreating assets. |
| Page draws but readiness fails | Compare the selected app's generated contract and `quartzui.build.manifest`; rebuild its bundle. A loaded HTML page is not a successful handshake. |
| `client.unavailable` in a desktop browser | The standalone browser has no native `window.ue.quartzui` gateway. Test the bridge inside Unreal. |
| `client.receiver-owned` | More than one client owns the same document. Retain one client and use subscription cleanup. |
| `quartzui.action.not-registered` | Register the action on that exact player's shell and validate its name/lifetime; a visible web button does not register native behavior. |
| Reference logs `bridge.endpoint-not-found` | The fixture can request an absent optional demo endpoint. Distinguish its rendering/readiness from an actual required gameplay provider. |
| DevTools reports no inspectable page | Start a live PIE/UI view and retry; do not reuse a stopped PIE target. |
| Empty DevTools with browser-Origin rejection | Check the baseline SHA. It is a known defect there; do not interpret passing discovery automation as a connection test. |
| Candidate inspector fails after Chrome update | Capture browser/Node versions and launcher log; revalidate the version-sensitive adapter. Keep Origin enforcement. |
| Audit passes but shipping behavior is unknown | Audit validates resource policy. A cook/package and launched packaged runtime remain separate untested gates. |

Source anchors in the plugin: `Documentation/EditorTools.md:1`, `Source/QuartzUIEditor/Public/QuartzUIEditorSettings.h`, `Source/QuartzUIEditor/Private/QuartzUIEditorModule.cpp`, and `Resources/Client/quartzui.mjs:45`. Native execution claims come from earlier independent baseline and candidate testing. The subsequent documentation review checked their consistency; it did not execute a new Editor session.

Canonical HTML: https://betterbuilt.games/docs/quartz-ui/debugging