Troubleshooting

Eight known failure modes with their fixes. If your problem is not on this page, jump to the Still stuck? section for a pre-filled GitHub issue template.

Launch and rendering problems

Why does Paneflow fail to launch with a GPU error?

Paneflow renders through GPUI, which needs Vulkan on Linux and Metal on macOS. A startup error like Failed to initialize renderer or No suitable GPU adapter found almost always means the platform GPU stack is missing or broken.

Linux fix:

# Debian / Ubuntu
sudo apt install libvulkan1 mesa-vulkan-drivers
# Fedora
sudo dnf install vulkan-loader mesa-vulkan-drivers
# Arch
sudo pacman -S vulkan-icd-loader mesa

Then run vulkaninfo --summary to confirm at least one ICD loads. macOS fix: update to macOS 13 Ventura or later - earlier versions ship a Metal API that GPUI does not support.

See the Linux install Vulkan note for the matching install-time dependency list.

Why is my Wayland session blank in Paneflow?

A blank window under Wayland is almost always the Vulkan ICD failing to negotiate a surface with the compositor. The window appears in the taskbar but renders no content.

Confirm the diagnosis with vulkaninfo --summary - if no driver lists VK_KHR_wayland_surface, you have the right symptom.

Force the XWayland fallback for a quick workaround:

WAYLAND_DISPLAY= GDK_BACKEND=x11 paneflow

Permanent fix: install your distribution's Mesa Vulkan driver package (mesa-vulkan-drivers on Debian / Ubuntu, vulkan-radeon or vulkan-intel on Fedora / Arch depending on your GPU vendor).

On NVIDIA proprietary drivers, ensure the package matches your running kernel - a stale module is the most common Wayland-blank root cause.

Configuration not taking effect

Why is my paneflow.json not loading?

Paneflow reads exactly one config file per OS and silently ignores unknown keys. A "config does not apply" complaint is almost always one of three things: wrong path, JSON syntax error, or the window_decorations exception (read at startup only).

Confirm the path:

Validate the JSON before saving:

cat ~/.config/paneflow/paneflow.json | python3 -m json.tool

A parse error means Paneflow silently falls back to defaults at next launch and logs a warning. Pin the JSON Schema to catch typos in your editor before saving.

window_decorations changes need a full restart - that key is read once at boot, not hot-reloaded.

Why are my shortcuts not working?

Three common causes:

1. Action name typo. Override values must match the canonical snake_case action name (split_horizontally, not split-horizontal or splitHorizontally). Unknown names are ignored. See the full list on the Keybindings reference.
2. Keystroke modifier mismatch. Use the form ctrl+shift+t, not ctrl-shift-t or Ctrl+Shift+T. Lowercase, plus-separated.
3. Context conflict. A binding in the Terminal context only fires when a terminal pane is focused. The Search and Markdown contexts are even narrower.

Override example:

{
  "shortcuts": {
    "ctrl+shift+t": "new_tab"
  }
}

If two entries map the same keystroke, the last one wins. See the override syntax for context-aware binding.

Why is my theme not hot-reloading?

Theme hot-reload uses a notify filesystem watcher with a 300 ms debounce, falling back to a 500 ms mtime poll when the watcher fails to start. If a saved paneflow.json change does not take effect within a second, one of three things is happening:

1. Theme name typo. Names are case-sensitive: "PaneFlow Light" works, "paneflow light" does not. Unknown names fall back to "One Dark" silently.
2. Filesystem doesn't support file watching. NFS shares, sandboxed app containers, and some WSL paths do not support inotify / FSEvents / ReadDirectoryChangesW. The 500 ms polling fallback should still work - if it does not, your editor is probably writing to a temp file and renaming, which on rare filesystems breaks the mtime signal.
3. You edited the wrong file. Confirm the path you saved matches the OS-specific location in the themes guide.

window_decorations is the only theme-adjacent key that is not hot-reloaded; that one needs a full restart.

Install and signing prompts

Why is paneflow not in my PATH?

Two install paths add paneflow to PATH automatically: the Linux .deb (drops a binary at /usr/bin/paneflow) and Homebrew (when the tap ships). The AppImage and tarball paths leave the binary wherever you put it.

Linux tarball fix:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Use ~/.zshrc for zsh or fish_add_path ~/.local/bin for fish. The Linux install PATH section covers the per-shell variants in detail.

macOS .app fix: the binary lives inside the bundle and is not on PATH by default. Symlink it once:

sudo ln -sf /Applications/Paneflow.app/Contents/MacOS/paneflow /usr/local/bin/paneflow

Why does macOS say Apple cannot check this app?

The notarized .dmg should never trigger this dialog, but if you moved the bundle through an unusual transfer path (downloaded via a non-Safari browser onto an external drive, copied through a network share) the quarantine attribute may have been preserved.

Fastest fix (one-time per app):

1. Open Finder, navigate to Applications.
2. Control-click Paneflow.app.
3. Choose Open.
4. Click Open in the confirmation dialog.

CLI fix:

xattr -d com.apple.quarantine /Applications/Paneflow.app

Removes the quarantine extended attribute system-wide for that bundle. No sudo required if you installed the app yourself. Full walk-through with the System Settings path lives on the macOS install page.

Still stuck?

If none of the above resolves your issue, open a GitHub issue with your OS, Paneflow version, and a reproduction. The link below opens a pre-filled template:

Open a GitHub issue

Paste any relevant output from RUST_LOG=info paneflow if the issue is reproducible from the CLI - the log lines tell us which subsystem failed and skip a round-trip of clarifying questions.