Dépannage

Huit modes de défaillance connus avec leurs correctifs. Si ton problème ne figure pas sur cette page, saute à la section Toujours bloqué ? pour un modèle d'issue GitHub pré-rempli.

Problèmes de lancement et de rendu

Pourquoi Paneflow échoue-t-il à se lancer avec une erreur GPU ?

Paneflow rend via GPUI, qui a besoin de Vulkan sur Linux et de Metal sur macOS. Une erreur au démarrage du type Failed to initialize renderer ou No suitable GPU adapter found signifie presque toujours que la pile GPU de la plateforme manque ou est cassée.

Correctif Linux :

# 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

Lance ensuite vulkaninfo --summary pour confirmer qu'au moins un ICD se charge. Correctif macOS : mets à jour vers macOS 13 Ventura ou ultérieur - les versions antérieures embarquent une API Metal que GPUI ne prend pas en charge.

Consulte la note Vulkan d'installation Linux pour la liste de dépendances d'installation correspondante.

Pourquoi ma session Wayland est-elle vide dans Paneflow ?

Une fenêtre vide sous Wayland est presque toujours l'ICD Vulkan qui échoue à négocier une surface avec le compositeur. La fenêtre apparaît dans la barre des tâches mais ne rend aucun contenu.

Confirme le diagnostic avec vulkaninfo --summary - si aucun pilote ne liste VK_KHR_wayland_surface, tu as le bon symptôme.

Force le repli XWayland pour un contournement rapide :

WAYLAND_DISPLAY= GDK_BACKEND=x11 paneflow

Correctif permanent : installe le paquet du pilote Mesa Vulkan de ta distribution (mesa-vulkan-drivers sur Debian / Ubuntu, vulkan-radeon ou vulkan-intel sur Fedora / Arch selon ton fabricant de GPU).

Sur les pilotes propriétaires NVIDIA, assure-toi que le paquet correspond à ton kernel en cours d'exécution - un module périmé est la cause racine la plus courante d'écran vide sous Wayland.

La configuration ne prend pas effet

Pourquoi mon paneflow.json ne se charge-t-il pas ?

Paneflow lit exactement un fichier de configuration par OS et ignore silencieusement les clés inconnues. Une plainte « la configuration ne s'applique pas » est presque toujours l'une de trois choses : mauvais chemin, erreur de syntaxe JSON, ou l'exception window_decorations (lue uniquement au démarrage).

Confirme le chemin :

Valide le JSON avant de sauvegarder :

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

Une erreur de parsing signifie que Paneflow retombe silencieusement sur les défauts au prochain lancement et logue un avertissement. Épingle le JSON Schema pour attraper les fautes de frappe dans ton éditeur avant de sauvegarder.

Les changements de window_decorations nécessitent un redémarrage complet - cette clé est lue une seule fois au boot, pas hot-reloadée.

Pourquoi mes raccourcis ne fonctionnent-ils pas ?

Trois causes courantes :

1. Faute de frappe dans le nom d'action. Les valeurs des surcharges doivent correspondre au nom d'action canonique en snake_case (split_horizontally, pas split-horizontal ni splitHorizontally). Les noms inconnus sont ignorés. Vois la liste complète sur la référence des raccourcis.
2. Désaccord de modificateur de frappe. Utilise la forme ctrl+shift+t, pas ctrl-shift-t ni Ctrl+Shift+T. Minuscules, séparés par des plus.
3. Conflit de contexte. Un raccourci dans le contexte Terminal ne se déclenche que quand un volet terminal est focalisé. Les contextes Search et Markdown sont encore plus étroits.

Exemple de surcharge :

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

Si deux entrées mappent la même frappe, la dernière l'emporte. Vois la syntaxe de surcharge pour des raccourcis sensibles au contexte.

Pourquoi mon thème ne se recharge-t-il pas à chaud ?

Le rechargement à chaud du thème utilise un watcher de système de fichiers notify avec un debounce de 300 ms, retombant sur un sondage mtime de 500 ms quand le watcher échoue à démarrer. Si un changement dans paneflow.json sauvegardé ne prend pas effet en une seconde, l'une de trois choses se passe :

1. Faute de frappe dans le nom du thème. Les noms sont sensibles à la casse : "PaneFlow Light" fonctionne, "paneflow light" non. Les noms inconnus retombent silencieusement sur "One Dark".
2. Le système de fichiers ne prend pas en charge la surveillance de fichiers. Les partages NFS, les conteneurs d'applications sandboxées et certains chemins WSL ne prennent pas en charge inotify / FSEvents / ReadDirectoryChangesW. Le repli par sondage à 500 ms devrait quand même marcher - si non, ton éditeur écrit probablement dans un fichier temporaire et le renomme, ce qui sur de rares systèmes de fichiers casse le signal mtime.
3. Tu as édité le mauvais fichier. Confirme que le chemin que tu as sauvegardé correspond à l'emplacement spécifique de l'OS dans le guide des thèmes.

window_decorations est la seule clé adjacente aux thèmes qui n'est pas hot-reloadée ; celle-ci nécessite un redémarrage complet.

Invites d'installation et de signature

Pourquoi paneflow n'est-il pas dans mon PATH ?

Deux chemins d'installation ajoutent paneflow au PATH automatiquement : le .deb Linux (dépose un binaire dans /usr/bin/paneflow) et Homebrew (quand le tap arrive). Les chemins AppImage et archive tar laissent le binaire où tu le mets.

Correctif archive tar Linux :

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

Utilise ~/.zshrc pour zsh ou fish_add_path ~/.local/bin pour fish. La section PATH d'installation Linux couvre les variantes par shell en détail.

Correctif .app macOS : le binaire vit à l'intérieur du bundle et n'est pas sur PATH par défaut. Fais un lien symbolique une seule fois :

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

Pourquoi macOS dit-il qu'Apple ne peut pas vérifier cette application ?

Le .dmg notarisé ne devrait jamais déclencher cette boîte de dialogue, mais si tu as déplacé le bundle par un chemin de transfert inhabituel (téléchargé via un navigateur non-Safari sur un disque externe, copié à travers un partage réseau), l'attribut de quarantaine peut avoir été préservé.

Correctif le plus rapide (une seule fois par application) :

1. Ouvre Finder, navigue vers Applications.
2. Control-clic sur Paneflow.app.
3. Choisis Ouvrir.
4. Clique sur Ouvrir dans la boîte de dialogue de confirmation.

Correctif CLI :

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

Retire l'attribut étendu de quarantaine à l'échelle du système pour ce bundle. Pas de sudo requis si tu as installé l'application toi-même. Le guide complet avec le chemin Réglages Système vit sur la page d'installation macOS.

Toujours bloqué ?

Si rien de ce qui précède ne résout ton problème, ouvre une issue GitHub avec ton OS, ta version de Paneflow et une reproduction. Le lien ci-dessous ouvre un modèle pré-rempli :

Ouvrir une issue GitHub

Colle toute sortie pertinente de RUST_LOG=info paneflow si le problème est reproductible depuis la CLI - les lignes de log nous disent quel sous-système a échoué et évitent un aller-retour de questions de clarification.