Troubleshooting

Find the symptom below and follow the matching checks. Change one thing at a time so you can tell what helped. If the problem persists, collect the diagnostics at the end of this page.

Launch and rendering

Why does Paneflow fail with a GPU or renderer error?

Linux: Paneflow needs a graphical session and a GPU driver with Vulkan support. Run this from a terminal in that session:

vulkaninfo --summary

If vulkaninfo is not found, install the vulkan-tools package with your distribution's package manager. A missing diagnostic tool does not mean Vulkan is unavailable.

If the command fails or lists no GPU, check the Vulkan loader and driver. The loader package is libvulkan1 on Debian/Ubuntu, vulkan-loader on Fedora, or vulkan-icd-loader on Arch. Install the Vulkan driver for your GPU: Mesa for supported Intel/AMD GPUs, or the appropriate NVIDIA driver. Restart Paneflow and keep any remaining error for the report.

macOS: Check that you have macOS 13 Ventura or later and an Apple Silicon Mac. Update macOS, then try again. See the macOS installation requirements.

Windows: For NoSupportedDeviceFound, update the GPU driver from your PC or GPU manufacturer, then restart Paneflow. The driver must support DirectX 11 feature level 10 or later. Record the GPU and driver details:

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

Why is my Wayland session blank?

A blank window can involve the graphics driver or the display server. It does not identify the cause by itself. Check Vulkan as described above, then quit Paneflow and try XWayland from the same graphical session:

env -u WAYLAND_DISPLAY paneflow

This requires XWayland and a working DISPLAY variable. It selects X11 for this launch only. If Paneflow opens this way, use it as a temporary workaround, check for graphics driver updates, and include the results of both launches in your report.

Configuration and shortcuts

Why is my paneflow.json not loading?

Check that you edited the configuration used by the running app. Release builds use these paths by default:

An absolute PANEFLOW_HOME override changes this folder. If you use one, adjust the paths in the commands below.

On Linux or macOS, with Python 3 installed:

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

On Windows:

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

Fix any reported syntax error, save the file, and try again. If the file is missing, Paneflow uses the defaults. Invalid configuration at startup also falls back to defaults; an invalid edit while Paneflow is running keeps the last valid configuration.

These commands check JSON syntax. Use the configuration schema reference to check setting names, types, and allowed values. Unknown top-level keys are ignored by the app, so a typo can look like an ignored setting.

Changes to window_decorations and window_backdrop require a restart.

Why are my shortcuts not working?

Each entry in shortcuts maps a key combination to an action name. For example, these entries create a tab with ctrl+shift+t and disable ctrl+shift+w. Merge them into the existing configuration:

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

Use the action names from the keyboard shortcut reference, such as new_tab, split_horizontally, or toggle_search. Unknown actions are skipped with a warning.

If a shortcut fails only in one place, check which view has focus. Terminal, Search, Markdown, and Diff actions have their own contexts.

Why is my theme not hot-reloading?

Use "One Dark" or "PaneFlow Light" for the top-level theme value. See the theme settings and examples.

1. Check the configuration path above, including any PANEFLOW_HOME override.
2. Check the JSON syntax and theme name, then save the file.
3. Wait briefly for the change to load. If it still does not apply, restart Paneflow.
4. If restarting applies the change but saving does not, report the problem and mention whether the file is on a network drive or mounted filesystem.

Installation and signing

Why is paneflow not in my PATH?

The fix depends on how you installed the app:

• Linux: The .deb and .rpm install the command in a system directory. AppImage and .tar.gz installs may need ~/.local/bin in your PATH. Follow the Linux command and PATH instructions.
• macOS: Installing PaneFlow.app with Homebrew or a DMG does not automatically add its executable to your shell's PATH. Follow the macOS terminal access instructions.
• Windows: Close terminal windows and reopen PowerShell from the Start menu after installing the MSI. If the command is still missing, follow the Windows command lookup steps.

Why does macOS say Apple cannot check this app?

The official DMG is signed and notarized. Download a fresh copy from the latest Paneflow release and check the alert's wording. Follow the macOS Gatekeeper steps, which distinguish a first-launch confirmation from a blocked app. For an alert that says the app is damaged or will harm the computer, keep it blocked and report the exact message.

Why does Windows SmartScreen block the MSI?

A signed installer can still trigger a SmartScreen reputation warning. Use the Windows signature verification steps before proceeding. Check that the signature is Valid and the publisher is Strivex. If either check fails, download the MSI again from the official release. If an organizational policy blocks installation, contact the administrator.

Collect diagnostics

What should I include in an issue?

If the app opens, choose Help > System Info, then Copy. Add that block, the shell you use, the exact error, steps to reproduce, and what you expected to happen. Mention which checks above you tried.

If the app does not open, provide the Paneflow version, OS version, architecture, install format, and GPU/driver details manually. On Windows, winver shows the Windows version and build.

Use the report for your platform:

To collect application output, quit Paneflow first, then launch it from a terminal with logging enabled. On Linux or macOS:

RUST_LOG=info paneflow

On Windows, for the default MSI install folder:

$env:RUST_LOG = "info"
$env:RUST_BACKTRACE = "1"
& "$env:ProgramFiles\PaneFlow\paneflow.exe"

If the command or executable is missing, follow the PATH section first or use the installed binary's full path. For a macOS DMG install, use /Applications/PaneFlow.app/Contents/MacOS/paneflow in place of paneflow.

Reproduce the problem and copy the relevant terminal output into the report. Remove tokens, private paths, or project content before posting it.

The read-only MCP bridge reads pane output. Use the commands above to collect application logs for launch, configuration, or rendering problems.