# 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** - Default 10GB 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 to ensure there won’t be any continual evictions/redownload
* **Check drive format** - Ensure cache drive is formatted as APFS (Mac) or NTFS (Windows). Do not use exFAT

#### 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 fails or slows down during active work

**Solutions:**

* **Avoid simultaneous operations** - Don't pin large amounts of data while actively accessing files through the mount
* **Separate workflows** - Complete pinning operations before intensive mount usage
* **Note:** Recent updates have fixed bugs where pinning could fail on network retry attempts

#### 5. Monitor Cache Drive Space

**Problem:** Unexpected performance degradation

**Solutions:**

* **Check free space** - Ensure sufficient available space on your cache drive
* **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: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.