v0.2.0 6e0cddc

troubleshooting.md RawHistoryFolder

Troubleshooting

  • No display: nefergui: open platform: ... wraps the Wayland connection error. Check WAYLAND_DISPLAY and XDG_RUNTIME_DIR, and that a Wayland compositor is running.
  • Missing protocol: Wayland capability <interface>: ... identifies the required compositor global. NeferGUI needs linux-dmabuf and linux-drm-syncobj; switch to a compositor offering both.
  • No suitable GPU: no Vulkan physical devices; need DRM main_device ..., no Vulkan DRM device matches linux-dmabuf main_device ..., or matching Vulkan device missing ... means the Vulkan driver cannot serve the compositor's DRM device. no one-plane exportable B8G8R8A8 modifier shared with compositor ... means they have no compatible modifier. Check driver and compositor support; there is no cross-GPU fallback.
  • Fonts: nefergui: fonts: no usable fonts: ... or nefergui: no usable fonts means system font discovery failed. Install usable TrueType/OpenType system fonts.
  • NEFERGUI_VULKAN_VALIDATION=1 enables Vulkan validation; an unavailable validation layer reports validation layer VK_LAYER_KHRONOS_validation unavailable. Install the validation layer or unset the variable. Broken implicit Vulkan layers can prevent startup: use VK_LOADER_LAYERS_DISABLE=<layer> to disable the offending layer for diagnosis.
  • NEFERGUI_DEBUG_DIR writes diagnostic artifacts, including frame-timings.jsonl and buffer-lifecycle.jsonl; choose a writable directory. Build with -tags nefergui_debug for identity diagnostics (duplicate keys, unkeyed type changes, stale handles).
  • To regenerate committed SPIR-V, install glslc and run go generate ./...; consumers do not need glslc.
  • If a requested font cannot be opened or parsed, text selection skips that face and tries the next matching face. Inspect catalog diagnostics for the failed path; system font discovery uses XDG font directories and does not require fontconfig.
source
1# Troubleshooting
2
3- No display: `nefergui: open platform: ...` wraps the Wayland connection error. Check `WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR`, and that a Wayland compositor is running.
4- Missing protocol: `Wayland capability <interface>: ...` identifies the required compositor global. NeferGUI needs linux-dmabuf and linux-drm-syncobj; switch to a compositor offering both.
5- No suitable GPU: `no Vulkan physical devices; need DRM main_device ...`, `no Vulkan DRM device matches linux-dmabuf main_device ...`, or `matching Vulkan device missing ...` means the Vulkan driver cannot serve the compositor's DRM device. `no one-plane exportable B8G8R8A8 modifier shared with compositor ...` means they have no compatible modifier. Check driver and compositor support; there is no cross-GPU fallback.
6- Fonts: `nefergui: fonts: no usable fonts: ...` or `nefergui: no usable fonts` means system font discovery failed. Install usable TrueType/OpenType system fonts.
7- `NEFERGUI_VULKAN_VALIDATION=1` enables Vulkan validation; an unavailable validation layer reports `validation layer VK_LAYER_KHRONOS_validation unavailable`. Install the validation layer or unset the variable. Broken implicit Vulkan layers can prevent startup: use `VK_LOADER_LAYERS_DISABLE=<layer>` to disable the offending layer for diagnosis.
8- `NEFERGUI_DEBUG_DIR` writes diagnostic artifacts, including `frame-timings.jsonl` and `buffer-lifecycle.jsonl`; choose a writable directory. Build with `-tags nefergui_debug` for identity diagnostics (duplicate keys, unkeyed type changes, stale handles).
9- To regenerate committed SPIR-V, install `glslc` and run `go generate ./...`; consumers do not need `glslc`.
10- If a requested font cannot be opened or parsed, text selection skips that face and tries the next matching face. Inspect catalog diagnostics for the failed path; system font discovery uses XDG font directories and does not require fontconfig.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 12

↑↓ moveenter openesc close