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