> 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/shadefs/shadefs-troubleshooting-guide.md).

# ShadeFS Troubleshooting Guide

### Performance Issues

#### 1. Optimize Cache Configuration

**Problem:** Slow file access and playback performance

**Solutions:**

* **Use an external SSD** - Connect a dedicated SSD (Samsung T7 recommended) for cache storage instead of using internal storage
* **Increase cache size** - The default 26GB may be insufficient for larger projects. Allocate based on your typical working set size. We recommend having a cache size at least as large as the largest file you are working with, because ShadeFS removes whole files when it frees up space. A smaller cache means that file keeps being removed and downloaded again.
* **Check drive format** - Ensure your cache drive is formatted as APFS (macOS), NTFS or ReFS (Windows), or ext4, XFS, or Btrfs (Linux). Do not use exFAT or Mac OS Extended (HFS+)

#### 2. Check Network Requirements

**Problem:** Stuttering playback or slow file loading

**Solutions:**

* **Verify internet speed** - Minimum 500Mbps download recommended for 4K content
* **Use wired connection** - Switch from WiFi to Ethernet when editing non-proxied assets
* **Test connection stability** - Ensure no packet loss or intermittent drops during active sessions

#### 3. Use Proxy Workflows

**Problem:** High-resolution content performs poorly

**Solutions:**

* **Enable proxy files** - Work with proxies instead of original high-res files, especially for 4K+ content
* **Ideal for limited bandwidth** - Significantly improves performance if under 500Mbps connection

#### 4. Manage Pinning and Mount Usage

**Problem:** Pinning is slow during active work

**Solutions:**

* **Expect pinning to yield to playback** - Files you open through the mounted drive always download ahead of pinned files. Pinning while you edit won't slow your playback, but the pin will take longer to finish.
* **Pin ahead of time** - If you need footage offline by a deadline, start pinning when you're not actively playing media so it gets the full connection

#### 5. Monitor Cache Drive Space

**Problem:** Unexpected performance degradation, or saving and copying to the mounted drive stalls

**Solutions:**

* **Check free space** - Ensure sufficient available space on your cache drive. When the cache drive is almost full, writes to the mounted drive pause until space frees up, and files that aren't cached may not open
* **Watch for space alerts** - The desktop app notifies you when your cache or cache drive is nearly full. Click the notification to open **Settings > ShadeFS > Cache Management**
* **Check your pins** - Pinned files don't count toward your cache size, so pinning large folders can fill the disk even when your cache size looks fine. Unpin what you no longer need from **Cache Management**
* **Right-size allocation** - Match cache size to your actual working set needs

### Getting Additional Help

If issues persist after trying these steps:

1. Go to Settings in the ShadeFS app
2. Export “ShadeFS Logs”
3. Share logs with support for investigation


---

# 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/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.
