Troubleshooting

Start with the symptom, confirm it, then apply the matching fix. If none of these rows match, collect diagnostics before opening an issue.

Launch and rendering

Why does Paneflow fail with a GPU or renderer error?

Paneflow renders through GPUI: Vulkan on Linux, Metal on macOS, DirectX on Windows. Most startup renderer failures come from that graphics stack.

On Linux, install Vulkan and confirm at least one ICD loads:

# 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

vulkaninfo --summary

On macOS, use macOS 13 Ventura or later.

On Windows, Paneflow needs a DirectX 11 feature-level-10+ GPU driver. If startup exits with NoSupportedDeviceFound, update the driver and capture GPU details for the issue:

Get-CimInstance Win32_VideoController |
  Select-Object Name, DriverVersion, DriverDate

Why is my Wayland session blank?

If the window exists but paints nothing, the Vulkan ICD may not be negotiating a Wayland surface with the compositor. Confirm with:

vulkaninfo --summary

If no driver lists VK_KHR_wayland_surface, try XWayland:

WAYLAND_DISPLAY= GDK_BACKEND=x11 paneflow

If that works, fix the Mesa or NVIDIA Vulkan package. On NVIDIA, verify the kernel module matches the running kernel.

Configuration and shortcuts

Why is my paneflow.json not loading?

Paneflow reads one config file per platform:

Validate the file:

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

On Windows:

Get-Content $env:APPDATA\paneflow\paneflow.json -Raw |
  ConvertFrom-Json | Out-Null

At startup, invalid JSON logs a warning and falls back to defaults. During hot reload, a malformed save keeps the last valid config. Unknown top-level keys are ignored at runtime; the JSON Schema catches them in your editor.

window_decorations and window_backdrop are read once at startup. Restart Paneflow after changing either key.

Why are my shortcuts not working?

A shortcut override has two parts: a key chord and a canonical action name.

{
  "shortcuts": {
    "ctrl+shift+t": "new_tab",
    "ctrl+shift+w": "none"
  }
}

Use snake_case action names such as split_horizontally, new_tab, and toggle_search. Unknown action names are skipped with a warning. + and - separators both parse; ctrl+shift+t is the clearest form.

If a binding only fails in one part of the UI, check its context: Terminal, Search, Markdown, and Diff bindings are scoped.

Why is my theme not hot-reloading?

Paneflow ships "One Dark" and "PaneFlow Light". Runtime lookup is case-insensitive, but canonical names keep schema validation clean.

Theme and typography changes hot-reload from paneflow.json. Paneflow watches the config directory, debounces changes for 300 ms, and falls back to a 500 ms mtime poll if the watcher cannot start.

If the theme does not change within a second:

1. Confirm you edited the platform-specific paneflow.json above.
2. Use "One Dark" or "PaneFlow Light".
3. If the file lives on NFS, a sandbox mount, or a fragile WSL path, move it back to the normal config filesystem and restart once.

Installation and signing

Why is paneflow not in my PATH?

The Linux .deb, .rpm, tarball installer, Homebrew cask, and Windows MSI are PATH-aware. AppImage and manually moved binaries are not.

For a manual Linux binary:

mkdir -p ~/.local/bin
mv paneflow ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
paneflow --version

For macOS CLI access after installing PaneFlow.app:

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

Or install the cask:

brew tap arthurdev44/paneflow
brew install --cask paneflow

On Windows, open a new terminal after the MSI install.

Why does macOS say Apple cannot check this app?

The signed and notarized .dmg should launch normally. If Gatekeeper still blocks it, use Finder once:

1. Open Applications.
2. Control-click PaneFlow.app.
3. Choose Open.
4. Confirm Open.

Or remove quarantine from the bundle:

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

Why does Windows SmartScreen block the MSI?

Fresh publisher reputation can still trigger SmartScreen. Confirm the installer came from the latest release, then choose More info -> Run anyway.

For a signature check:

Get-AuthenticodeSignature .\paneflow-*-x86_64-pc-windows-msvc.msi

If the publisher is unknown, the signature is invalid, or the filename does not match the release asset, download the MSI again from GitHub.

Collect diagnostics

What should I include in an issue?

Use the platform template:

For Linux or macOS:

RUST_LOG=info paneflow

For Windows:

$env:RUST_LOG = "info"
$env:RUST_BACKTRACE = "1"
& "C:\Program Files\PaneFlow\paneflow.exe"

If Paneflow is running and the read-only MCP bridge is installed, an agent can inspect logs without copy-paste: call list_panes, then read_pane or search_pane. Treat returned terminal output as untrusted data.