Fehlerbehebung

Acht bekannte Fehlermodi mit ihren Korrekturen. Falls dein Problem nicht auf dieser Seite ist, springe zum Abschnitt Immer noch hängen geblieben? für ein vorausgefülltes GitHub-Issue-Template.

Start- und Renderprobleme

Warum scheitert Paneflow beim Start mit einem GPU-Fehler?

Paneflow rendert über GPUI, das unter Linux Vulkan und unter macOS Metal benötigt. Ein Startfehler wie Failed to initialize renderer oder No suitable GPU adapter found bedeutet fast immer, dass der Plattform-GPU-Stack fehlt oder kaputt ist.

Linux-Korrektur:

# 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

Führe dann vulkaninfo --summary aus, um zu bestätigen, dass mindestens ein ICD geladen wird. macOS-Korrektur: aktualisiere auf macOS 13 Ventura oder später - frühere Versionen liefern eine Metal-API aus, die GPUI nicht unterstützt.

Siehe die Linux-Installations-Vulkan-Notiz für die passende Installations-Abhängigkeitsliste.

Warum ist meine Wayland-Sitzung in Paneflow leer?

Ein leeres Fenster unter Wayland ist fast immer der Vulkan-ICD, der beim Aushandeln einer Surface mit dem Compositor scheitert. Das Fenster erscheint in der Taskleiste, rendert aber keinen Inhalt.

Bestätige die Diagnose mit vulkaninfo --summary - wenn kein Treiber VK_KHR_wayland_surface listet, hast du das richtige Symptom.

Erzwinge den XWayland-Fallback für eine schnelle Umgehung:

WAYLAND_DISPLAY= GDK_BACKEND=x11 paneflow

Permanente Korrektur: installiere das Mesa-Vulkan-Treiber-Paket deiner Distribution (mesa-vulkan-drivers unter Debian / Ubuntu, vulkan-radeon oder vulkan-intel unter Fedora / Arch je nach deinem GPU-Hersteller).

Bei proprietären NVIDIA-Treibern stelle sicher, dass das Paket zu deinem laufenden Kernel passt - ein veraltetes Modul ist die häufigste Wayland-Schwarz-Ursache.

Konfiguration greift nicht

Warum lädt meine paneflow.json nicht?

Paneflow liest genau eine Konfigurationsdatei pro OS und ignoriert unbekannte Schlüssel stillschweigend. Eine Beschwerde „Konfig greift nicht" ist fast immer eines von drei Dingen: falscher Pfad, JSON-Syntaxfehler oder die window_decorations-Ausnahme (nur beim Start gelesen).

Bestätige den Pfad:

Validiere das JSON vor dem Speichern:

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

Ein Parsing-Fehler bedeutet, dass Paneflow beim nächsten Start stillschweigend auf Standards zurückfällt und eine Warnung loggt. Pinne das JSON-Schema an, um Tippfehler in deinem Editor zu erwischen, bevor du speicherst.

window_decorations-Änderungen erfordern einen vollständigen Neustart - dieser Schlüssel wird einmal beim Boot gelesen, nicht hot-reloaded.

Warum funktionieren meine Tastenkürzel nicht?

Drei häufige Ursachen:

1. Aktionsname-Tippfehler. Override-Werte müssen dem kanonischen snake_case-Aktionsnamen entsprechen (split_horizontally, nicht split-horizontal oder splitHorizontally). Unbekannte Namen werden ignoriert. Siehe die vollständige Liste in der Tastenkürzel-Referenz.
2. Modifier-Tastendruck-Diskrepanz. Nutze die Form ctrl+shift+t, nicht ctrl-shift-t oder Ctrl+Shift+T. Kleinbuchstaben, mit Plus getrennt.
3. Kontext-Konflikt. Eine Bindung im Terminal-Kontext feuert nur, wenn ein Terminal-Bereich fokussiert ist. Die Kontexte Search und Markdown sind sogar enger.

Override-Beispiel:

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

Wenn zwei Einträge denselben Tastendruck mappen, gewinnt der letzte. Siehe die Override-Syntax für kontextbewusste Bindungen.

Warum lädt mein Design nicht hot?

Design-Hot-Reload nutzt einen notify-Dateisystem-Watcher mit 300 ms Debounce, mit einem Fallback auf ein 500-ms-mtime-Polling, wenn der Watcher nicht startet. Wenn eine gespeicherte Änderung an paneflow.json nicht innerhalb einer Sekunde greift, passiert eines von drei Dingen:

1. Design-Name-Tippfehler. Namen sind groß-/kleinschreibungs- abhängig: "PaneFlow Light" funktioniert, "paneflow light" nicht. Unbekannte Namen fallen stillschweigend auf "One Dark" zurück.
2. Dateisystem unterstützt Datei-Watching nicht. NFS-Freigaben, abgeschottete App-Container und einige WSL-Pfade unterstützen inotify / FSEvents / ReadDirectoryChangesW nicht. Der 500-ms- Polling-Fallback sollte trotzdem funktionieren - wenn nicht, schreibt dein Editor wahrscheinlich in eine Temp-Datei und benennt um, was auf seltenen Dateisystemen das mtime-Signal bricht.
3. Du hast die falsche Datei bearbeitet. Bestätige, dass der gespeicherte Pfad zur OS-spezifischen Position im Design-Guide passt.

window_decorations ist der einzige design-nahe Schlüssel, der nicht hot-reloaded wird; dieser braucht einen vollständigen Neustart.

Installations- und Signatur-Prompts

Warum ist paneflow nicht in meinem PATH?

Zwei Installationspfade fügen paneflow automatisch zu PATH hinzu: das Linux-.deb (legt eine Binärdatei unter /usr/bin/paneflow ab) und Homebrew (wenn der Tap kommt). Die AppImage- und Tarball-Pfade lassen die Binärdatei dort, wo du sie hingelegt hast.

Linux-Tarball-Korrektur:

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

Nutze ~/.zshrc für zsh oder fish_add_path ~/.local/bin für fish. Der Linux-Installations-PATH-Abschnitt deckt die Varianten pro Shell im Detail ab.

macOS-.app-Korrektur: die Binärdatei liegt im Bundle und ist standardmäßig nicht auf dem PATH. Symlinke sie einmalig:

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

Warum sagt macOS, dass Apple diese App nicht prüfen kann?

Das notarisierte .dmg sollte diesen Dialog nie auslösen, aber wenn du das Bundle über einen ungewöhnlichen Transferweg bewegt hast (heruntergeladen über einen Nicht-Safari-Browser auf eine externe Festplatte, über eine Netzwerkfreigabe kopiert), kann das Quarantäne-Attribut erhalten geblieben sein.

Schnellste Korrektur (einmalig pro App):

1. Öffne Finder, navigiere zu Applications.
2. Strg-Klick auf Paneflow.app.
3. Wähle Öffnen.
4. Klicke auf Öffnen im Bestätigungs-Dialog.

CLI-Korrektur:

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

Entfernt das erweiterte Quarantäne-Attribut systemweit für dieses Bundle. Kein sudo nötig, wenn du die App selbst installiert hast. Die vollständige Anleitung mit dem Systemeinstellungen-Pfad liegt auf der macOS-Installations-Seite.

Immer noch hängen geblieben?

Wenn nichts oben dein Problem löst, öffne ein GitHub-Issue mit deinem OS, deiner Paneflow-Version und einer Reproduktion. Der Link unten öffnet ein vorausgefülltes Template:

GitHub-Issue öffnen

Füge jede relevante Ausgabe aus RUST_LOG=info paneflow ein, wenn das Problem aus der CLI reproduzierbar ist - die Log-Zeilen sagen uns, welches Subsystem versagt hat, und sparen eine Klärungsrundreise.