Skip to main content

Troubleshooting

Check the current call's return value. On failure, read Get Last Desktop Window Error immediately. Its stored error can survive later successful calls; do not treat an old message as the result of a new request.

Set Hotkey or Set Presentation returns NotActive​

Widget Construct and BeginPlay can run before automatic activation. Follow Quick Start: bind status first, check current status immediately, and guard initialization with an active-host check. Filter shutdown statuses. Do not use a fixed Delay.

If status stays Disabled, check Enable Packaged Desktop Mode, the run environment, and -DGTDisable. For Failed, inspect the actual error.

Set Presentation returns HotkeyUnavailable​

Set Desktop Toggle Hotkey must return Success this launch before requesting Transparent. An execution wire alone does not confirm success. Get Desktop Toggle Hotkey returns false without registration. Keep Opaque and offer another binding if registration fails.

Set Hotkey returns HotkeyUnavailable or Unsupported​

HotkeyUnavailable: Windows refused the chord, possibly because another program owns it. Try another combination. A failed rebind preserves the old binding.

Unsupported: choose a supported keyboard key. Mouse/gamepad inputs, modifier-only keys, F12, and unmapped keys are rejected. See Hotkeys.

The background is black or opaque​

Check Get Desktop Presentation Mode; Opaque is normal at startup. If already Transparent:

  • Enable Alpha Output and Frame Buffer Pixel Format: 8bit RGBA.
  • Resolve Get Project Configuration Issues.
  • Follow the sky/cloud Holdout setup and fog limitation. Remove other content covering the background, such as floors, post-process effects, or opaque full-screen widgets.
  • Restart when required and repackage after configuration changes.

See Installation.

Opaque objects look translucent at opacity 1​

In Transparent mode, Set Whole Window Opacity: 1.0 preserves the frame's per-pixel alpha. In UE 5.5, ExponentialHeightFog > Holdout can reduce that alpha even over Opaque materials.

Disable ExponentialHeightFog temporarily. If the objects become solid, fog holdout is the cause. Keep the fog disabled for a clear background with solid objects. Turning only Holdout off can make the background opaque again.

PIE or Standalone behaves differently​

In-viewport PIE is unsupported. Use a packaged Win64 client or a separate Standalone Game process with -DGTStandalonePreview. Keep the desktop setting enabled. GPU desktop window active in the child process log confirms activation, not transparency.

Clear pixels receive clicks, or the window disappears​

Interactive receives clicks over the entire rectangle. ClickThrough passes them all through and requires Transparent. If foreground focus is refused after recovery, click the Interactive host.

Opacity 0 hides the frame without changing input. Restore opacity through game logic; the shortcut only toggles input.

Click-drag camera input has zero Mouse X/Y​

Use Interactive input and keep the game window focused. Captured/high precision mouse movement is forwarded through Windows raw input, while normal cursor movement and UMG clicks use the regular mouse messages.

If an Enhanced Input action fires but Mouse X/Y stay zero, check the Player Controller's input/capture mode: the game viewport must capture the mouse for those axes. Also check the action's mapping and triggers. Read Mouse X/Y while holding the button, and restore cursor/input mode on both Completed and Canceled.

Selecting a display does not move the game​

RestartRequired means the preference was saved. Relaunch to apply it. Missing monitors fall back to primary. For live bounds, use Set Desktop Window Rect. See Displays.

Nodes are missing or the package fails​

Enable the matching plugin version and restart the Editor. Keep its Content folder and modules: DesktopGameToolkitEarly, DesktopGameToolkitBootstrap, and DesktopGameToolkit. Inspect the first relevant build/cook error.

Collect diagnostics​

Launch with -DGTDiag for %TEMP%/DGTStartup-<process-id>.txt. Review the trace before sharing. -DGTDisable opens a normal recovery window; desktop nodes remain inactive.

For Discord support, include versions, DX11/DX12, context, reproduction, return value, error, and logs.