Window Framework for UI Toolkit v2.0.x
Troubleshooting

Start with the smallest check that explains the symptom. A missing reference, the wrong theme scope, an unprepared value, or a selector that does not match is usually more useful to investigate than resetting the project.

This page explains documented configuration requirements and current limitations. It is not a list of reproduced fixes for every possible Unity error. If the checks do not explain your result, use the reporting checklist at the end rather than changing unrelated systems.

Required First Checks

  1. Read the first relevant Console error and its full stack trace. Later errors may be consequences. Keep the message before making changes; do not clear useful evidence to hide it.
  2. Confirm compilation and requirements. Check Asset Requirements, including optional package availability for the features in use.
  3. Confirm the intended host. Inspect the controller's linked UIDocument, its PanelSettings/root UXML, and its ThemeData reference.
  4. Confirm the source you are editing. The Studio editing theme, runtime active theme, configured default, and Addressables active collection are different choices.
  5. Change one relevant item, then check again. Do not delete assets, disable unrelated components, clear every preference, or add compatibility defines as a general repair.

Windows and Layout

The Controller Exists, but No Windows Appear

Checks:** Is the UIDocument linked and enabled with its panel/root assigned? Did your application add window content after the controller root became available? Is the window hidden or outside the expected layout?

Resolution:** Follow 3. Bring the Setup Into Your Scene and 2. Create Your First Window. The generated repository root is intentionally blank; it does not include Demo windows or your application content. Add the intended content through the existing creation path rather than adding another controller.

A Startup/Window Call Reports a Null Reference

Checks:** Read the failing file/line. For controller startup, verify the linked UIDocument or the UIDocument on the same GameObject. For an application/window action, verify the controller/session/target actually exists at that lifecycle point.

Resolution:** Fix the missing or premature connection, then retry after initialization. Constructing a WindowFrame does not create its controller. If the required references are present and the exception persists, report the exact stack; do not assume every null exception has the same cause or remove components to suppress it.

A Controller or UI Host Disappears During Startup

Checks:** The controller is a singleton and persists across scene loads. Did a later scene introduce another controller while the existing host was still alive? What other components/references belong to those objects?

Resolution:** Deliberately configure one intended host across that scene flow. The current duplicate-controller path removes the duplicate object; do not depend on it to preserve unrelated components on that object. Review ownership before removing any project object. See 3. Bring the Setup Into Your Scene.

Opening a Window Activates an Existing One Instead

Checks:** Is AllowMultipleInstances false on the incoming window? Does an existing registered frame have the same VisualElement.name?

Resolution:** Use intentional unique instance names when multiples are required, or retain/use the existing singleton-style instance. The duplicate check is name-based, not WindowId-based. The rejected instance's application resources still need their owner's cleanup. See Instance Names and Memory IDs Are Different.

Initial Position/Size Is Unexpected or a Change Has No Effect

Checks:** Inspect eligible saved geometry, explicit USS/inline positions and dimensions, StartPosition, LockedToStartPosition, and panel scale. Were DefaultWidth/DefaultHeight assigned after attachment? Is the parent layout available yet?

Resolution:** Configure creation-time defaults before mounting, choose placement/memory ownership deliberately, and wait for layout before geometry-dependent operations. Those default-size properties do not reactively resize an attached window. See 4. Choose Size and Starting Position; do not erase all saved data to diagnose one window.

A Window Cannot Move, Resize, Close, or Leave Fullscreen

Checks:** Review AllowMove, ShowHeader, AllowResize, AllowClose, Locked, AllowFullscreen and LockedFullscreen. Are you expecting a hidden header to remain a drag handle? Is this the intentionally locked Demo toolbar?

Resolution:** Adjust the intended window policy only. Some flags govern user interaction while direct APIs have their own rules; Force All is not a substitute for application authorization. See 5. Set Window Permissions and 8. Show, Hide, Activate, and Close.

Docking/Tabs Behave Differently From Floating Windows

Checks:** Separate snapping from dock rectangles and fullscreen. Verify attached parent dimensions, both windows' tab-docking permissions, current tab indices, and content constraints.

Resolution:** Use DockTo/Undock and DockTab/SwitchToTab/UndockTab through their documented paths. Test half-area layouts with the actual content; dock rectangles are not a promise that every content minimum will fit. A tab's X detaches it rather than automatically cancelling its business data. See 6. Snapping and Screen Docking and 7. Combine Windows Into Tabs.

A Window Does Not Restore, or Restores to an Old Layout

Checks:** Controller Memory Enabled, per-window WindowMemoryEnabled, a concrete derived window type, nonempty stable WindowId and appropriate ParentObjectId. Did the type/IDs change? Is LockedToStartPosition or explicit application placement overriding restoration?

Resolution:** Reconstruct the same logical application window with consistent identifiers and current content. A bare WindowFrame is excluded by the writer. ReopenWindows requires a resolvable type/parameterless reconstruction path; use your application's own creation path when injection or owner data is needed. See 9. Remember Window Layouts. Player themes and preference resets do not override the controller's memory enablement policy.

Stylesheets and Theme Scope

Before changing a value, distinguish its variable, class, ID, and required component/state selector.

Unity Warns That PanelSettings Has No Theme Style Sheet

Checks:** Is the missing reference unintended, or does the existing controller deliberately install its configured application/theme sheets at runtime? Confirm that controller/root initialization and configured native/application roles are valid before treating the warning as harmless.

Resolution:** A PanelSettings theme is not a required placeholder dependency for WindowFramework. The supplied controller-managed panel intentionally permits a null theme reference. In Unity versions providing the per-panel no-theme-warning option, the supplied panel marks this intentional configuration using that option; this does not disable other Console warnings or supply missing styles. A developer-owned panel may instead provide its own baseline. Do not force a WindowFramework palette or require a named placeholder file on arbitrary project panels. If the controller/application rules are missing, fix those connections rather than opting out of a valid diagnostic.

A Class Added in Code Does Not Apply the Expected Style

Checks:** Exact case/spelling; no leading dot in AddToClassList; a real rule for that class; correct element type and ancestor/state; registered application USS; themed scope; more specific/inline values.

Resolution:** Follow 5. Theme Your Own Control and 7. Understand Overrides and Inheritance. A custom-property name is not a class. Reusing Content Background normally means your application rule reads var(–wfw-surface-background); assigning windowFrame imports much more than that one background. Use Built-in Styling Class Reference to check whether a role is reusable or structural.

Custom Controls Outside Windows Stay Unthemed—or Other UI Changes

Checks:** Is Theme Apply Method Window Frames Only, Parent Panel, or All Panels? Does the custom control sit beneath the styled/bound scope? Do broad native-control rules affect another interface in that panel?

Resolution:** Select the smallest intended scope and register your application rules. Panel-wide styling can affect existing native labels/buttons even without your custom class. All Panels is styling, not cross-document modal input blocking. See Make Sure the Theme Reaches the Control.

A Palette Looks Wrong After Switching Themes

Checks:** Three essential application roles first; additional application rules in the correct order; only the selected theme settings appended; optional Global Stylesheet load order; your application's independently attached or inline rules.

Resolution:** Correct the collection references/order in Shared Stylesheets. Do not attach every theme palette or duplicate the full shared wrapper as another layer. Keep other UI owners' styles intact. See 2. Follow the Actual Composition Order and 4. Register Your Application Stylesheet.

Theme Studio, Saving, and Artwork

Studio Shows a Legacy/Unavailable Preview Instead of Modern Controls

Checks:** The actual selected TSS, its imports, the configured application roles, and source-read diagnostics. Is it genuinely legacy, missing, or unable to provide a valid modern graph?

Resolution:** Use the legacy upgrade workflow for a real 1.0 source; repair missing modern references when that is the problem instead. Upgrade creates separate output and is not automatic conversion of every custom layout. See 12. Upgrade Legacy Themes and Remove Entries Carefully and Stylesheet Setup and Theme Structure.

The Wrong Theme Appears Active or Default

Checks:** EDITING, ACTIVE and DEFAULT badges, the current ThemeData collection, and runtime player selection. Did you only click a Studio row?

Resolution:** Use the intended Set Active/Set Default action; editing selection alone changes neither role. Check one valid default and stable identities. See 3. Editing, Active, and Default Are Different and 8. Refresh, Select, and Restore.

Save To Disk Is Blocked or Edits Seem Lost

Checks:** Matching TSS/USS base filenames and expected source file; developer validation messages; editable source availability; external source changes since loading. Did you switch editing themes or duplicate before saving tokens?

Resolution:** Save supported token edits before switching/duplicating. Duplicate reads saved source, not unsaved inspector values. Reconcile/reload externally changed developer source rather than overwriting another author. Metadata controls and collection actions have their own persistence behavior; selection is not a universal undo. See 10. Save the Authored Result and 4. Start With an Existing Theme or an Independent Copy.

A Linked Field Is Read-Only or Its Override Switch Disappeared

Checks:** The authored expression and current linked/independent mode. Did you save a literal override and reload it?

Resolution:** Enable Override on an eligible linked component row for an independent value. An already authored literal has no original link to expose; saving/reloading a literal does not retain a permanent automatic reset target. Reestablish an authored alias in source when that is your intended policy. See 7. Keep Component Values Linked—or Override Them.

An Image Cannot Be Assigned, Is Missing, or Looks Different

Checks:** The picker-supported type, runtime Resources placement, unique resource reference, declaring-file-relative URL, and actual image file. Distinguish preview thumbnail, window background, default indicator and cursor artwork.

Resolution:** Assign the appropriate supported asset/reference; do not relocate or overwrite unrelated artwork to satisfy a field. Saving changes references, not source image pixels. Developer image fields require Texture2D; configured framework vector support does not make every image pipeline accept SVG. Check the target-platform rendering/cursor behavior separately. See 8. Assign Images, Icons, and Cursors and Images.

Developer Extensions

A Developer Field Does Not Appear

Checks:** Declaring file in the configured graph; Developer section markers; immediate WFWDevExt comment before the variable; line-based metadata; valid namespace/key/type/constraints; non-framework variable prefix.

Resolution:** Inspect the existing example.hotbar declaration/application files in 3. Open the Existing Files and 4. Read the Existing Annotations. Correct that source instead of adding a competing declaration or another sample control. Repeated identities keep the first definition and warn; they do not replace its default.

A Field Appears in Studio/JSON but Does Not Change the Control

Checks:** Registered application USS, supported property beginning with the intended var reference, resolved default, supported selector, exact class/type/ID/ancestor/state, saved/current preparation, and runtime scope. Is the field exported with no supported consumer?

Resolution:** Seeing a field is not proof of a prepared target. Follow 5. Follow the Existing Application Rules and Structure, 7. Use Supported Property and Selector Mappings and 9. Prepare the Theme for Player Use. The existing hotbar child classes require the actual ToolbarWindowExample.windowFrame ancestor. Do not replace that type requirement with a similarly named class.

Newly Added Controls Do Not Receive Player Overrides

Checks:** Classes assigned at construction; current hierarchy/ancestors; actual active player theme; attachment/reconciliation integration.

Resolution:** Use the existing owner and PlayerThemeRuntime.RefreshControls after application-owned matching/hierarchy changes. Geometry alone is not target discovery. Do not create a second registry/session for the same UI. See 11. Account for Runtime Ownership and Dynamic UI and 10. Integrate With Your Existing UI Owner.

Player Themes and Copying

The existing picker distinguishes usable themes, recoverable warnings, and unavailable entries. Use View Issues before changing unrelated configuration.

Copy/Refresh Controls Are Disabled or the Session Is Not Ready

Checks:** Player Themes enabled on the intended collection; controller/root initialization; built-in stable IDs/default; deferred Addressables hydration; current session published to ThemeData.

Resolution:** Complete the configured startup/preparation workflow rather than constructing a duplicate owner or theme dataset. Open Theme Folder is desktop-gated. See Required Developer Setup and 1. Understand the Player Workflow.

Copy Reports Missing Preparation, Values, Font, or Scope

Checks:** The selected built-in snapshot, or prepared configured default for an imported source; current source/assets/metadata; exported font identity; attached resolved scope within the configured application scopes; source unchanged during async rendering.

Resolution:** Save and prepare the intended modern source, check the report, then use the existing copy workflow. The async path supports configured vector rasterization; the synchronous raster path can refuse compiled vectors. Do not fabricate missing defaults or rewrite player folders to bypass scope/preparation checks. See 11. Prepare Values When Offering Player Themes and 2. Create an Independent Editable Copy.

Create Copy Rejects a Name or a Copy Was Saved but Not Selected

Checks:** One valid 1–80-character folder name; forbidden/reserved characters; case-insensitive file/folder collisions; the exact creation/selection report.

Resolution:** Choose a valid unused name. A committed copy remains if later refresh/selection fails; refresh and select that folder instead of recreating it blindly. Cancellation does not remove an already committed independent copy. See Copy Names and Folder Identity and 2. Create an Independent Editable Copy.

A Player Folder Is Not Listed or Has an Unavailable Badge

Checks:** Immediate child of the configured persistent root; required theme.json; formatVersion/id/name; supported keys/groups; valid paths; unique player IDs; storage access; folder/discovery limits.

Resolution:** Open View Issues, correct the specified file/data, save and refresh. Duplicate IDs reject all matching entries; preserve a copy's generated ID and use distinct identities for independent copies. A malformed file is not fixed by adding another controller or changing unrelated theme values. See 3. Find the Editable Files, 4. Edit theme.json and 9. Read Warnings and Unavailable Entries.

A Theme Loads With a Warning or Some Values Stay at Defaults

Checks:** Reported recognized field type/range; missing/corrupt image; configured font identifier; known-extension value validity. Compare against Portable Framework Field Reference.

Resolution:** Correct only the reported values/files and refresh. Missing/recovered overrides retain defaults; image null explicitly clears, while omission retains. Unknown framework fields or unknown keys within a known generated extension are not equivalent to recoverable typed-value errors. See 9. Read Warnings and Unavailable Entries and 7. Customize the Existing Demo Hotbar.

Changes to JSON, Name, Preview, or Images Do Not Appear

Checks:** The actual file under the correct player folder; valid JSON; saved changes; explicit Refresh Player Themes; selected stable identity; the relevant preview versus appearance field. Does nameSource equal folder?

Resolution:** Refresh saved files, then Set Active for a different theme. Generated copies use their folder name for display; preserve their ID and required JSON metadata when renaming. Unreferenced files are not automatic overrides. Use contained raster references and configured font IDs. See 4. Edit theme.json, 5. Replace Artwork and Preview Images and 6. Use Configured Fonts, Not Loose Font Files.

Resetting Appearance Did Not Delete Copies or Change Memory

Checks:** Which operation you invoked: default selection, preference reset, or manual filesystem change.

Resolution:** Default selection releases player-value bindings but keeps editable folders. Memory enablement is controller policy. Deleting/reorganizing player files is a separate deliberate action requiring refresh and attention to active identity; do not use wholesale deletion as the first diagnostic. See 8. Refresh, Select, and Restore.

Tooltips, Context Menus, and Modals

A Tooltip Never Appears on New Content

Checks:** Tooltip text, enabled preferences, initialization timing, installation on dynamically added content, userData marker ownership, hover/drag/capture behavior and source removal.

Resolution:** Apply tooltip behavior to the new subtree after the controller exists; do not install duplicate manipulators or overwrite the automatic marker to force refresh. Respect the configured delay and cancellation behavior. See 1. Add Contextual Help With Tooltips.

A Menu Is Missing, Anchored Unexpectedly, or Has Stale Row States

Checks:** Attached target, trigger/focus path, valid ordered configuration and nonnull state predicates, current model at construction, modal eligibility, and target-based placement.

Resolution:** Reopen for fresh predicate evaluation; IsDisabled true means disabled. Screen-position arguments do not guarantee arbitrary cursor placement in the current renderer. The optional Show onClose callback is for successful item activation, not every dismissal. See 2. Put Item Actions in a Context Menu.

Modal Content Does Not Block Another UI or Escape Does Not Close It

Checks:** Controller-owned ShowModal presentation, detached content before ownership, linked document sorting, actual focus, independent documents and gameplay input policy, card/window dismissal permissions.

Resolution:** Use the existing modal host and deliberately coordinate other UI/input. Styling all panels does not create cross-document input ownership. Escape dismissal is not automatically installed; use an appropriate cancellation route honoring user-dismissal rules. A required card can reject RequestDismiss; application-authorized close methods should not become an unconditional cancel shortcut. See 5. Coordinate Focus, Input, and Cancellation and User Dismissal Is Not Application Completion.

Addressables Loading

The Wrong Collection Loads—or Loading Fails

Checks:** Installed supported package and enabled integration; Addressables settings/group schemas; actual entries/addresses/labels; exactly the intended active collection label; content built for the target; correct build/load paths and test mode.

Resolution:** Follow Optional: Addressables Theme Loading. Opening a ThemeData in Studio is not assigning Addressable Default. Setup Labels scans discovered ThemeData assets, so inspect its resulting entries rather than assuming only the open repository changed. Rebuild/test the intended content path; do not weaken package guards, add unrelated defines, or modify package source to suppress a loading error.

Visual Scripting

Nodes Are Missing or the Sample Graph Does Nothing

Checks:** Optional package/assembly compilation, node-library availability, a listening graph/ScriptMachine, real controller/targets, populated inputs and connected flow.

Resolution:** Regenerate the node library when appropriate after fixing compilation. The supplied sample graph is an unwired palette with blank name inputs, not an auto-running Demo sequence. Wire the intended flow and use existing windows. See Required Setup and 1. Inspect the Existing Demo Material.

Node Options Failed to Load and Were Skipped

Symptom:** The Console reports that some node options failed to load and were skipped, often listing removed Unity types or WindowFramework types under an old assembly name.

Checks:** Confirm the installed Visual Scripting package and a clean project compilation. The generated node library can be stale after Unity/package updates, assembly moves, or changes to custom node ports. This is an editor cache/setup issue, not a requirement imposed on users of the built demo.

Resolution:** When using the optional Visual Scripting integration, open Edit > Project Settings > Visual Scripting > Node Library, choose Regenerate Nodes, and confirm. In package versions showing the action on the main Visual Scripting settings page, use that Regenerate Nodes action. Wait for generation, then check a fresh Console/Play Mode entry. This may be needed during initial setup or relevant updates; it should not be required for every Play Mode entry or for projects not using Visual Scripting. Do not delete graphs or edit package source to suppress stale-option warnings. If rebuilding still reports skipped entries, preserve the remaining list and investigate those types/package versions specifically.

A Graph Exits but the Requested Result Is Missing

Checks:** Reference before name fallback; exact Title/element name, not GameObject/persistence ID; cached result read after execution; real layout; normal permissions; available controller/theme configuration.

Resolution:** Exit is synchronous return, not success/layout/fade completion. Show does not construct or focus a missing window. Theme units operate on the built-in collection, not player stable IDs. See 2. Use the Right Window Identity, 3. Control Flow Is Not Completion, 4. Window Units and 5. Theme Units.

Graph Events or Later Menu Callbacks Stop Arriving

Checks:** Native event unit versus bridge Custom Event route; target GameObject, exact event name and argument type; graph/bridge enabled lifetime; shared native relay listener lifetimes; active menu callback owner.

Resolution:** Match the documented event contract. Bridge arguments are title/theme-name strings, not WindowFrame objects. Current native relays are not independent reference-counted listeners, and the context-menu dismissal unit only searches its documented subtree. Test those preview limits in the real graph ownership setup. See 7. Native Framework Event Units, 8. Use Window Scripting Bridge for Custom Events and 6. Tooltip and Context Menu Units.

If the Checks Do Not Explain the Problem

Provide a focused report with:

  • Unity version, target platform, and relevant package versions.
  • The exact expected result and actual result.
  • Steps to reproduce using the existing Demo where applicable, or the smallest relevant application flow.
  • Intended scene/controller/UIDocument/ThemeData and editing/active/default roles.
  • The first relevant Console message and full stack, plus View Issues/preparation reports when involved.
  • The relevant selector/value/reference and whether it is authored, inline, player-overridden, or restored state.
  • What changed immediately before the issue and which single checks you already tried.

Screenshots of the affected interface and assigned references can help. Redact private data, credentials and unnecessary machine-specific paths before posting a public report.

Do not present an untested hypothesis as a verified fix. If an issue remains after the documented configuration is correct, stop changing surrounding systems and investigate that specific behavior. Preserve source, player files and reproduction evidence so the underlying cause can be resolved.