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

## Launch and rendering problems [#launch-and-rendering-problems]

### Why does Paneflow fail to launch with a GPU error? [#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:**

```bash
# 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](/docs/installation/linux) for the
matching install-time dependency list.

### Why is my Wayland session blank in Paneflow? [#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:

```bash
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 [#configuration-not-taking-effect]

### Why is my paneflow\.json not loading? [#why-is-my-paneflowjson-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:**

| OS    | Path                                                   |
| ----- | ------------------------------------------------------ |
| Linux | `~/.config/paneflow/paneflow.json`                     |
| macOS | `~/Library/Application Support/paneflow/paneflow.json` |

**Validate the JSON** before saving:

```bash
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](/docs/configuration#editor-autocomplete-with-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? [#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](/docs/keybindings).
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](/docs/keybindings#search-overlay) and
   [Markdown](/docs/keybindings#markdown-pane) contexts are even
   narrower.

Override example:

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

If two entries map the same keystroke, the last one wins. See the
[override syntax](/docs/configuration/schema#how-do-i-set-shortcuts)
for context-aware binding.

### Why is my theme not hot-reloading? [#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](/docs/themes#how-do-i-switch-the-active-theme).

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

## Install and signing prompts [#install-and-signing-prompts]

### Why is paneflow not in my PATH? [#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:**

```bash
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](/docs/installation/linux#what-if-paneflow-is-not-found-in-my-path)
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:

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

### Why does macOS say Apple cannot check this app? [#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:**

```bash
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](/docs/installation/macos#what-if-macos-gatekeeper-blocks-the-app).

## Still stuck? [#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**](https://github.com/ArthurDEV44/paneflow/issues/new?title=%5Bbug%5D%20short%20summary\&body=%23%23%20Environment%0A-%20OS%3A%20%28Linux%20distro%20%2B%20version%20%2F%20macOS%20version%29%0A-%20Paneflow%20version%3A%20%28paneflow%20--version%29%0A-%20GPU%20%2F%20driver%3A%20%0A-%20Display%20server%20%28Linux%29%3A%20Wayland%20%2F%20X11%0A%0A%23%23%20Steps%20to%20reproduce%0A1.%20%0A2.%20%0A3.%20%0A%0A%23%23%20Expected%20behaviour%0A%0A%0A%23%23%20Actual%20behaviour%0A%0A%0A%23%23%20Logs%20%2F%20screenshots%0A)

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.