> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/shade-academy/shade-academy-fr/shadefs/shadefs-troubleshooting-guide.md).

# Guide de dépannage de ShadeFS

### Problèmes de performance

#### 1. Optimiser la configuration du cache

**Problème :** Accès aux fichiers et performances de lecture lentes

**Solutions :**

* **Utiliser un SSD externe** - Connectez un SSD dédié (Samsung T7 recommandé) pour le stockage du cache au lieu d’utiliser le stockage interne
* **Augmenter la taille du cache** - La valeur par défaut de 26 Go peut être insuffisante pour les projets plus volumineux. Allouez de l’espace en fonction de votre taille de jeu de travail habituelle. Nous recommandons d’avoir une taille de cache au moins aussi grande que le plus gros fichier sur lequel vous travaillez, car ShadeFS supprime des fichiers entiers lorsqu’il libère de l’espace. Un cache plus petit signifie que ce fichier est constamment supprimé puis téléchargé à nouveau.
* **Vérifier le format du disque** - Assurez-vous que votre disque de cache est formaté en APFS (macOS), NTFS ou ReFS (Windows), ou ext4, XFS, ou Btrfs (Linux). N’utilisez pas exFAT ni Mac OS étendu (HFS+)

#### 2. Vérifier les exigences réseau

**Problème :** Lecture saccadée ou chargement lent des fichiers

**Solutions :**

* **Vérifier la vitesse d’Internet** - Un débit descendant minimum de 500 Mbit/s est recommandé pour le contenu 4K
* **Utiliser une connexion filaire** - Passez du Wi‑Fi à Ethernet lors de l’édition d’éléments non proxifiés
* **Tester la stabilité de la connexion** - Veillez à n’avoir aucune perte de paquets ni coupures intermittentes pendant les sessions actives

#### 3. Utiliser des flux de travail proxy

**Problème :** Le contenu haute résolution donne de mauvaises performances

**Solutions :**

* **Activer les fichiers proxy** - Travaillez avec des proxys au lieu des fichiers originaux en haute résolution, surtout pour le contenu 4K et plus
* **Idéal pour une bande passante limitée** - Améliore considérablement les performances si la connexion est inférieure à 500 Mbit/s

#### 4. Gérer l’épinglage et l’utilisation du montage

**Problème :** L’épinglage est lent pendant le travail actif

**Solutions :**

* **Attendez-vous à ce que l’épinglage passe après la lecture** - Les fichiers que vous ouvrez via le lecteur monté se téléchargent toujours avant les fichiers épinglés. Épingler pendant que vous modifiez ne ralentira pas votre lecture, mais l’épinglage prendra plus de temps à se terminer.
* **Épinglez à l’avance** - Si vous avez besoin de séquences hors ligne avant une échéance, commencez l’épinglage lorsque vous ne lisez pas activement de média afin qu’il bénéficie de toute la connexion

#### 5. Surveiller l’espace du disque de cache

**Problème :** Dégradation inattendue des performances, ou blocage de l’enregistrement et de la copie vers le lecteur monté

**Solutions :**

* **Vérifier l’espace libre** - Assurez-vous que l’espace disponible sur votre disque de cache est suffisant. Lorsque le disque de cache est presque plein, les écritures vers le lecteur monté sont mises en pause jusqu’à ce que de l’espace se libère, et les fichiers qui ne sont pas mis en cache peuvent ne pas s’ouvrir
* **Surveillez les alertes d’espace** - L’application de bureau vous avertit lorsque votre cache ou votre disque de cache est presque plein. Cliquez sur la notification pour l’ouvrir **Paramètres > ShadeFS > Gestion du cache**
* **Vérifiez vos fichiers épinglés** - Les fichiers épinglés ne sont pas comptabilisés dans la taille de votre cache, donc l’épinglage de grands dossiers peut remplir le disque même lorsque la taille de votre cache semble correcte. Désépinglez ce dont vous n’avez plus besoin dans **Gestion du cache**
* **Ajuster l’allocation** - Faites correspondre la taille du cache à vos besoins réels en matière de jeu de travail

### Obtenir une aide supplémentaire

Si les problèmes persistent après avoir essayé ces étapes :

1. Allez dans Paramètres dans l’application ShadeFS
2. Exportez « ShadeFS Logs »
3. Partagez les journaux avec le support pour examen


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/shade-academy/shade-academy-fr/shadefs/shadefs-troubleshooting-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
