[GH-ISSUE #318] Wolf-UI main screen black, but apps able to launch and be seen #220

New issue

Open

opened 2026-10-15 12:58:22 +00:00 by bsakaguchi · 14 comments

bsakaguchi commented 2026-10-15 12:58:22 +00:00

Owner

Copy link

Originally created by @Kamalaja on GitHub (Dec 18, 2025).
Original GitHub issue: https://github.com/games-on-whales/wolf/issues/318

Hey! I installed wolf and accidentally used my APU as the gpu before setting the correct GPU via environment variables.

Now, the WolfUI in moonlight only shows a black screen and mouse. BUT the apps that I installed are navigable via the keyboard and can be launched.

When i launch firefox or XFCE terminal, the apps do get displayed in moonlight, but exiting back to WolfUI shows the same black screen. I am not sure what to do next.

Originally created by @Kamalaja on GitHub (Dec 18, 2025). Original GitHub issue: https://github.com/games-on-whales/wolf/issues/318 Hey! I installed wolf and accidentally used my APU as the gpu before setting the correct GPU via environment variables. Now, the WolfUI in moonlight only shows a black screen and mouse. BUT the apps that I installed are navigable via the keyboard and can be launched. When i launch firefox or XFCE terminal, the apps do get displayed in moonlight, but exiting back to WolfUI shows the same black screen. I am not sure what to do next.

bsakaguchi commented 2026-10-15 12:58:23 +00:00

Author

Owner

Copy link

@Greaper88 commented on GitHub (Dec 19, 2025):

Add WOLF_LOG_LEVEL=DEBUG to your compose/env and post the full logs please.

<!-- gh-comment-id:3672813913 --> @Greaper88 commented on GitHub (Dec 19, 2025): Add `WOLF_LOG_LEVEL=DEBUG` to your compose/env and post the full logs please.

bsakaguchi commented 2026-10-15 12:58:23 +00:00

Author

Owner

Copy link

@Kamalaja commented on GitHub (Dec 19, 2025):

Hey! Thanks for the response - here are the logs

wolf.log

<!-- gh-comment-id:3672840786 --> @Kamalaja commented on GitHub (Dec 19, 2025): Hey! Thanks for the response - here are the logs [wolf.log](https://github.com/user-attachments/files/24247722/wolf.log)

bsakaguchi commented 2026-10-15 12:58:23 +00:00

Author

Owner

Copy link

@Greaper88 commented on GitHub (Dec 19, 2025):

Looks like you're using nVidia? Are you using the toolkit or manual method?
Also, are you trying to use separate render/encode devices?

<!-- gh-comment-id:3672952578 --> @Greaper88 commented on GitHub (Dec 19, 2025): Looks like you're using nVidia? Are you using the toolkit or manual method? Also, are you trying to use separate render/encode devices?

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@Kamalaja commented on GitHub (Dec 19, 2025):

System setup:

• Nvidia RTX 3080, RTX 3070, AMD 5700g

In an ideal world, I would use the 3080 for render and the 5700g for encode. I don't believe I am doing that right now. Right now I should just be using the 3080. Here is my compose file. I am using the toolkit method ATM

version: "3"
services:
  wolf:
    image: ghcr.io/games-on-whales/wolf:stable
    environment:
      - NVIDIA_DRIVER_CAPABILITIES=all
      - NVIDIA_VISIBLE_DEVICES=all
      - WOLF_RENDER_NODE=/dev/dri/renderD129
      - WOLF_LOG_LEVEL=DEBUG
    volumes:
      - /etc/wolf/:/etc/wolf
      - /var/run/docker.sock:/var/run/docker.sock:rw
      - /dev/:/dev/:rw
      - /run/udev:/run/udev:rw
    device_cgroup_rules:
      - 'c 13:* rmw'
    devices:
      - /dev/dri
      - /dev/uinput
      - /dev/uhid
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    network_mode: host
    restart: unless-stopped```

<!-- gh-comment-id:3672989789 --> @Kamalaja commented on GitHub (Dec 19, 2025): System setup: - Nvidia RTX 3080, RTX 3070, AMD 5700g In an ideal world, I would use the 3080 for render and the 5700g for encode. I don't believe I am doing that right now. Right now I should just be using the 3080. Here is my compose file. I am using the toolkit method ATM ```yaml version: "3" services: wolf: image: ghcr.io/games-on-whales/wolf:stable environment: - NVIDIA_DRIVER_CAPABILITIES=all - NVIDIA_VISIBLE_DEVICES=all - WOLF_RENDER_NODE=/dev/dri/renderD129 - WOLF_LOG_LEVEL=DEBUG volumes: - /etc/wolf/:/etc/wolf - /var/run/docker.sock:/var/run/docker.sock:rw - /dev/:/dev/:rw - /run/udev:/run/udev:rw device_cgroup_rules: - 'c 13:* rmw' devices: - /dev/dri - /dev/uinput - /dev/uhid deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] network_mode: host restart: unless-stopped```

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@Greaper88 commented on GitHub (Dec 19, 2025):

So, the toolkit method is considered unreliable, and the manual method is preferred. The below script will handle setting up the volume itself for you and you just need to switch to the manual compose, but make sure you carry over any customization, such as - WOLF_RENDER_NODE=/dev/dri/renderD129 and - WOLF_LOG_LEVEL=DEBUG.

curl https://raw.githubusercontent.com/games-on-whales/gow/master/images/nvidia-driver/Dockerfile | docker build -t gow/nvidia-driver:latest -f - --build-arg NV_VERSION=$(cat /sys/module/nvidia/version) .
docker create --rm --mount source=nvidia-driver-vol,destination=/usr/nvidia gow/nvidia-driver:latest sh
docker volume ls | grep nvidia-driver

Another thing you can do is disable the zero copy pipeline by adding WOLF_USE_ZERO_COPY=FALSE to your environment. This will result in a slight performance hit.
If you do wish to perform split render/encode pipelines (which is very bad for performance) this must be in your environment.

<!-- gh-comment-id:3673007879 --> @Greaper88 commented on GitHub (Dec 19, 2025): So, the toolkit method is considered unreliable, and the manual method is preferred. The below script will handle setting up the volume itself for you and you just need to switch to the manual compose, but make sure you carry over any customization, such as ` - WOLF_RENDER_NODE=/dev/dri/renderD129` and `- WOLF_LOG_LEVEL=DEBUG`. ```bash curl https://raw.githubusercontent.com/games-on-whales/gow/master/images/nvidia-driver/Dockerfile | docker build -t gow/nvidia-driver:latest -f - --build-arg NV_VERSION=$(cat /sys/module/nvidia/version) . docker create --rm --mount source=nvidia-driver-vol,destination=/usr/nvidia gow/nvidia-driver:latest sh docker volume ls | grep nvidia-driver ``` Another thing you can do is disable the zero copy pipeline by adding `WOLF_USE_ZERO_COPY=FALSE` to your environment. This will result in a slight performance hit. If you do wish to perform split render/encode pipelines (which is very bad for performance) this must be in your environment.

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@Kamalaja commented on GitHub (Dec 19, 2025):

So, the toolkit method is considered unreliable, and the manual method is preferred. The below script will handle setting up the volume itself for you and you just need to switch to the manual compose, but make sure you carry over any customization, such as - WOLF_RENDER_NODE=/dev/dri/renderD129 and - WOLF_LOG_LEVEL=DEBUG.

curl https://raw.githubusercontent.com/games-on-whales/gow/master/images/nvidia-driver/Dockerfile | docker build -t gow/nvidia-driver:latest -f - --build-arg NV_VERSION=$(cat /sys/module/nvidia/version) .
docker create --rm --mount source=nvidia-driver-vol,destination=/usr/nvidia gow/nvidia-driver:latest sh
docker volume ls | grep nvidia-driver

Another thing you can do is disable the zero copy pipeline by adding WOLF_USE_ZERO_COPY=FALSE to your environment. This will result in a slight performance hit. If you do wish to perform split render/encode pipelines (which is very bad for performance) this must be in your environment.

Hey! I tried the manual method, and unfortunately now I am unable to get anything from the wolf UI - here are my logs and docker-compose

version: "3"
services:
  wolf:
    image: ghcr.io/games-on-whales/wolf:stable
    environment:
      - NVIDIA_DRIVER_VOLUME_NAME=nvidia-driver-vol
      - WOLF_RENDER_NODE=/dev/dri/renderD129
      - WOLF_LOG_LEVEL=DEBUG
    volumes:
      - /mnt/root/random/random2/steam/etc/wolf/:/etc/wolf:rw
      - /var/run/docker.sock:/var/run/docker.sock:rw
      - /dev/:/dev/:rw
      - /run/udev:/run/udev:rw
      - nvidia-driver-vol:/usr/nvidia:rw
    devices:
      - /dev/dri
      - /dev/uinput
      - /dev/uhid
      - /dev/nvidia-uvm
      - /dev/nvidia-uvm-tools
      - /dev/nvidia-caps/nvidia-cap1
      - /dev/nvidia-caps/nvidia-cap2
      - /dev/nvidiactl
      - /dev/nvidia0
      - /dev/nvidia-modeset
    device_cgroup_rules:
      - 'c 13:* rmw'
    network_mode: host
    restart: unless-stopped

volumes:
  nvidia-driver-vol:
    external: true

wolf2.log

<!-- gh-comment-id:3675784084 --> @Kamalaja commented on GitHub (Dec 19, 2025): > So, the toolkit method is considered unreliable, and the manual method is preferred. The below script will handle setting up the volume itself for you and you just need to switch to the manual compose, but make sure you carry over any customization, such as ` - WOLF_RENDER_NODE=/dev/dri/renderD129` and `- WOLF_LOG_LEVEL=DEBUG`. > > curl https://raw.githubusercontent.com/games-on-whales/gow/master/images/nvidia-driver/Dockerfile | docker build -t gow/nvidia-driver:latest -f - --build-arg NV_VERSION=$(cat /sys/module/nvidia/version) . > docker create --rm --mount source=nvidia-driver-vol,destination=/usr/nvidia gow/nvidia-driver:latest sh > docker volume ls | grep nvidia-driver > > Another thing you can do is disable the zero copy pipeline by adding `WOLF_USE_ZERO_COPY=FALSE` to your environment. This will result in a slight performance hit. If you do wish to perform split render/encode pipelines (which is very bad for performance) this must be in your environment. Hey! I tried the manual method, and unfortunately now I am unable to get anything from the wolf UI - here are my logs and docker-compose ```yaml version: "3" services: wolf: image: ghcr.io/games-on-whales/wolf:stable environment: - NVIDIA_DRIVER_VOLUME_NAME=nvidia-driver-vol - WOLF_RENDER_NODE=/dev/dri/renderD129 - WOLF_LOG_LEVEL=DEBUG volumes: - /mnt/root/random/random2/steam/etc/wolf/:/etc/wolf:rw - /var/run/docker.sock:/var/run/docker.sock:rw - /dev/:/dev/:rw - /run/udev:/run/udev:rw - nvidia-driver-vol:/usr/nvidia:rw devices: - /dev/dri - /dev/uinput - /dev/uhid - /dev/nvidia-uvm - /dev/nvidia-uvm-tools - /dev/nvidia-caps/nvidia-cap1 - /dev/nvidia-caps/nvidia-cap2 - /dev/nvidiactl - /dev/nvidia0 - /dev/nvidia-modeset device_cgroup_rules: - 'c 13:* rmw' network_mode: host restart: unless-stopped volumes: nvidia-driver-vol: external: true ``` [wolf2.log](https://github.com/user-attachments/files/24261851/wolf2.log)

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@Kamalaja commented on GitHub (Dec 19, 2025):

Update: I reinstalled wolf (nvidia container version) and set both my render node and devices to be /dev/dri/renderD129 and that appears to have fixed it. Cheers

<!-- gh-comment-id:3676824532 --> @Kamalaja commented on GitHub (Dec 19, 2025): Update: I reinstalled wolf (nvidia container version) and set both my render node and devices to be `/dev/dri/renderD129` and that appears to have fixed it. Cheers

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@Kamalaja commented on GitHub (Dec 29, 2025):

re-opening as it appears to have come back - this is very peculiar

<!-- gh-comment-id:3697549296 --> @Kamalaja commented on GitHub (Dec 29, 2025): re-opening as it appears to have come back - this is very peculiar

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@Kamalaja commented on GitHub (Jan 10, 2026):

Still having this issue - this is persisting across multiple reinstalls and using either container toolkit or manual driver install. Happy to provide logs :)

<!-- gh-comment-id:3733327209 --> @Kamalaja commented on GitHub (Jan 10, 2026): Still having this issue - this is persisting across multiple reinstalls and using either container toolkit or manual driver install. Happy to provide logs :)

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@I-am-PUID-0 commented on GitHub (Jun 23, 2026):

I think I may have hit a related issue on a TrueNAS/NVIDIA setup.

This was tested against a local build of Wolf stable at commit 0a4e766:

0a4e766 Merge pull request #438 from wolph/fix/stale-container-monitor-loop

In my case, direct Moonlight app launchers worked, and Wolf-UI itself appeared to start, but the Wolf-UI screen was black with only the cursor visible. The important log lines were from Godot/Vulkan:

ERROR: Condition "err != VK_SUCCESS" is true. Returning: SwapChainID()
ERROR: Unable to create swap chain.
ERROR: A swap chain was not created for the screen.
Godot Engine v4.4.1.stable.mono.official.49a5bc7b6
Vulkan 1.3.277 - Forward+ - Using Device #0: NVIDIA - NVIDIA RTX 2000 Ada Generation

Launching apps from Wolf-UI/direct launchers still worked, so the Wolf server, Moonlight path, GPU, and app containers were basically healthy. The failure seemed isolated to Wolf-UI’s Godot Vulkan/Forward+ rendering path.

I worked around it by building a tiny local Wolf-UI image that keeps the upstream image but forces Godot’s Compatibility/OpenGL renderer:

FROM ghcr.io/games-on-whales/wolf-ui:main

RUN sed -i \
  's/launcher wolf-ui -f -t/launcher wolf-ui -f -t --rendering-method gl_compatibility --rendering-driver opengl3/' \
  /opt/gow/startup-app.sh

Then I used that image for the Wolf-UI app:

image = 'local/wolf-ui:gl-compat'

After that Wolf-UI rendered correctly. The working log showed:

OpenGL API 3.3.0 NVIDIA 550.142 - Compatibility - Using Device: NVIDIA - NVIDIA RTX 2000 Ada Generation
Wolf-UI started.

So this may not be exactly the same root cause, especially since your issue mentions initially using the APU, but the symptom is very similar: Wolf-UI black screen/cursor while launched apps render fine.

A possible upstream-friendly fix might be to let the Wolf-UI container accept extra Godot args through an env var, something like:

WOLF_UI_ARGS="--rendering-method gl_compatibility --rendering-driver opengl3"

or a dedicated renderer setting, so users with Vulkan/swapchain problems can select the compatibility renderer without patching startup-app.sh.

<!-- gh-comment-id:4780577566 --> @I-am-PUID-0 commented on GitHub (Jun 23, 2026): I think I may have hit a related issue on a TrueNAS/NVIDIA setup. This was tested against a local build of Wolf `stable` at commit [0a4e766](https://github.com/games-on-whales/wolf/commit/0a4e7665bfb4c9e0f73f1c7b6ee05cd61c7d5272): ```text 0a4e766 Merge pull request #438 from wolph/fix/stale-container-monitor-loop ``` In my case, direct Moonlight app launchers worked, and Wolf-UI itself appeared to start, but the Wolf-UI screen was black with only the cursor visible. The important log lines were from Godot/Vulkan: ```text ERROR: Condition "err != VK_SUCCESS" is true. Returning: SwapChainID() ERROR: Unable to create swap chain. ERROR: A swap chain was not created for the screen. Godot Engine v4.4.1.stable.mono.official.49a5bc7b6 Vulkan 1.3.277 - Forward+ - Using Device #0: NVIDIA - NVIDIA RTX 2000 Ada Generation ``` Launching apps from Wolf-UI/direct launchers still worked, so the Wolf server, Moonlight path, GPU, and app containers were basically healthy. The failure seemed isolated to Wolf-UI’s Godot Vulkan/Forward+ rendering path. I worked around it by building a tiny local Wolf-UI image that keeps the upstream image but forces Godot’s Compatibility/OpenGL renderer: ```dockerfile FROM ghcr.io/games-on-whales/wolf-ui:main RUN sed -i \ 's/launcher wolf-ui -f -t/launcher wolf-ui -f -t --rendering-method gl_compatibility --rendering-driver opengl3/' \ /opt/gow/startup-app.sh ``` Then I used that image for the Wolf-UI app: ```toml image = 'local/wolf-ui:gl-compat' ``` After that Wolf-UI rendered correctly. The working log showed: ```text OpenGL API 3.3.0 NVIDIA 550.142 - Compatibility - Using Device: NVIDIA - NVIDIA RTX 2000 Ada Generation Wolf-UI started. ``` So this may not be exactly the same root cause, especially since your issue mentions initially using the APU, but the symptom is very similar: Wolf-UI black screen/cursor while launched apps render fine. A possible upstream-friendly fix might be to let the Wolf-UI container accept extra Godot args through an env var, something like: ```text WOLF_UI_ARGS="--rendering-method gl_compatibility --rendering-driver opengl3" ``` or a dedicated renderer setting, so users with Vulkan/swapchain problems can select the compatibility renderer without patching `startup-app.sh`.

bsakaguchi commented 2026-10-15 12:58:24 +00:00

Author

Owner

Copy link

@ABeltramo commented on GitHub (Jun 23, 2026):

Thanks for the in-depth explanation @I-am-PUID-0 sounds like we should open an issue in Wolf UI @Skerga are you aware of this?

<!-- gh-comment-id:4780910525 --> @ABeltramo commented on GitHub (Jun 23, 2026): Thanks for the in-depth explanation @I-am-PUID-0 sounds like we should open an issue in Wolf UI @Skerga are you aware of this?

bsakaguchi commented 2026-10-15 12:58:25 +00:00

Author

Owner

Copy link

@Skerga commented on GitHub (Jun 23, 2026):

I'll have a look, if this can be fixed by using the OpenGL 3 Backend then I would also go the way of using a env var, maybe even default to the OpenGL Version if that increases compatibility.

<!-- gh-comment-id:4781055040 --> @Skerga commented on GitHub (Jun 23, 2026): I'll have a look, if this can be fixed by using the OpenGL 3 Backend then I would also go the way of using a env var, maybe even default to the OpenGL Version if that increases compatibility.

bsakaguchi commented 2026-10-15 12:58:25 +00:00

Author

Owner

Copy link

@Skerga commented on GitHub (Jun 23, 2026):

I've pushed an update that implements the Env var WOLF_UI_ARGS that @I-am-PUID-0 suggested, see here

<!-- gh-comment-id:4782286371 --> @Skerga commented on GitHub (Jun 23, 2026): I've pushed an update that implements the Env var `WOLF_UI_ARGS` that @I-am-PUID-0 suggested, see [here](https://github.com/games-on-whales/wolf-ui/pull/15)

bsakaguchi commented 2026-10-15 12:58:25 +00:00

Author

Owner

Copy link

@I-am-PUID-0 commented on GitHub (Jun 23, 2026):

I've pushed an update that implements the Env var WOLF_UI_ARGS that @I-am-PUID-0 suggested, see here

Thanks for the quick response and fix!

Confirmed working on my TrueNAS/NVIDIA setup after pulling the updated image.

Environment:

• TrueNAS SCALE
• NVIDIA RTX 2000 Ada
• Wolf local build from stable commit 0a4e766
• Wolf UI image: ghcr.io/games-on-whales/wolf-ui:main
• Pulled digest: sha256:cd6de1158b29068e4a4d4ce6312976067517239be97200a391be758a6ddfcf9b

Verified the image has the new args passthrough:

/opt/gow/startup-app.sh:16:opts=( $WOLF_UI_ARGS )

This app config now works for me:

image = "ghcr.io/games-on-whales/wolf-ui:main"

env = [
    "GOW_REQUIRED_DEVICES=/dev/input/event* /dev/dri/* /dev/nvidia*",
    "WOLF_SOCKET_PATH=/var/run/wolf/wolf.sock",
    "WOLF_UI_ARGS=--rendering-method gl_compatibility --rendering-driver opengl3",
    "WOLF_UI_AUTOUPDATE=False",
    "LOGLEVEL=INFO",
]

Wolf UI now renders correctly with the OpenGL compatibility args.

<!-- gh-comment-id:4782732387 --> @I-am-PUID-0 commented on GitHub (Jun 23, 2026): > I've pushed an update that implements the Env var `WOLF_UI_ARGS` that [@I-am-PUID-0](https://github.com/I-am-PUID-0) suggested, see [here](https://github.com/games-on-whales/wolf-ui/pull/15) Thanks for the quick response and fix! Confirmed working on my TrueNAS/NVIDIA setup after pulling the updated image. Environment: - TrueNAS SCALE - NVIDIA RTX 2000 Ada - Wolf local build from `stable` commit `0a4e766` - Wolf UI image: `ghcr.io/games-on-whales/wolf-ui:main` - Pulled digest: `sha256:cd6de1158b29068e4a4d4ce6312976067517239be97200a391be758a6ddfcf9b` Verified the image has the new args passthrough: ```text /opt/gow/startup-app.sh:16:opts=( $WOLF_UI_ARGS ) ``` This app config now works for me: ```toml image = "ghcr.io/games-on-whales/wolf-ui:main" env = [ "GOW_REQUIRED_DEVICES=/dev/input/event* /dev/dri/* /dev/nvidia*", "WOLF_SOCKET_PATH=/var/run/wolf/wolf.sock", "WOLF_UI_ARGS=--rendering-method gl_compatibility --rendering-driver opengl3", "WOLF_UI_AUTOUPDATE=False", "LOGLEVEL=INFO", ] ``` Wolf UI now renders correctly with the OpenGL compatibility args.

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

beta

feat/fedora-base-images

stable

axolotlitehotfix/randomly-generated-client-id

feat/vulkan-image

ci/image-smoke-harness

nv12-producer-pin

fix/nvidia-zero-copy

fix/amd-dma-buf-negotiation

fix/joypad-input-leak

codex/party-mode-split-render

ci-fedora-images

test/gst-wld-block-linear

fix/nvidia-blackwell-zero-copy

feat/embed-wolf-den

fix/fake-udev-write-db

fix/session-runner-user

fedora-dockerfile

feat/comprehensive-display-modes

aimee/quickstart-scripts

JBailes-patch-1

dev-nix

dev-fake-uinput

dev-tracy

fix/gst_vaapi

v2024.07

v2023.06

v2023.02

v2022.11

Labels

Clear labels   

🧠 1 - 🤖 999

  

AMD

  

bug

  

bug

  

cannot reproduce

  

documentation

  

duplicate

  

easy

  

enhancement

  

enhancement

  

enhancement

  

fixed?

  

fixed?

  

good first issue

  

hard

  

help wanted

  

Intel

  

invalid

  

LXC

  

medium

  

moonlight-protocol

  

Multi GPU

  

nixos

  

not a bug

  

nvidia

  

pull-request

Mirrored from GitHub Pull Request

  

question

  

wontfix

No labels

🧠 1 - 🤖 999

AMD

bug

bug

cannot reproduce

documentation

duplicate

easy

enhancement

enhancement

enhancement

fixed?

fixed?

good first issue

hard

help wanted

Intel

invalid

LXC

medium

moonlight-protocol

Multi GPU

nixos

not a bug

nvidia

pull-request

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

games-on-whales/wolf#220

No description provided.