Troubleshooting

Common Issues

Server Not Showing in Claude Desktop

1. Check config file path is correct

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Verify executable path is absolute (not relative)

   • Correct: C:\\Tools\\filesystem-ultra.exe
   • Incorrect: .\filesystem-ultra.exe

3. Check Claude Desktop logs

   • Windows: %APPDATA%\Claude\logs\
   • Look for MCP-related errors

4. Validate JSON syntax

   • Use a JSON validator
   • Common issue: missing commas or trailing commas

”Access Denied” Errors

• Ensure paths are in allowed paths (positional arguments or --allowed-paths)
• Check Windows file permissions
• Verify paths exist and are accessible
• Run Claude Desktop as administrator (if needed)

Slow Performance

• Increase --cache-size (try 500MB)
• Increase --parallel-ops (try 16)
• Enable --compact-mode to reduce overhead
• Check if antivirus is scanning files

High Memory Usage

• Reduce --cache-size
• Reduce --parallel-ops
• Large cache sizes increase memory usage proportionally

Timeouts on Large Files

• The v4 unified read_file and write_file automatically select the optimal strategy based on file size — no separate “intelligent” tool is needed in v4.x.
• These tools pick direct I/O for small files, streaming for medium files, chunked processing for large files, and special handling for >5 MB files.

Edit Operations Failing

• Verify old_text matches exactly (including whitespace).
• For mixed-indent files (tabs vs spaces) or CRLF/LF mismatches, pass tolerant_whitespace: true to edit_file / multi_edit (v4.5.7+).
• Check file encoding (UTF-8 recommended).
• If the file changed on disk since you read it, either pass expected_hash (OCC token from read_file’s structuredContent.content_hash, or the content_hash field returned by write_file since v4.5.26) or set --auto-occ=off (v4.5.17+).
• For third-party MCP clients that don’t see the text trailer: read the content_hash field directly from structuredContent (see Structured Output).

Backup Directory Issues

• Ensure backup directory is in allowed paths
• Verify write permissions to backup location
• Check available disk space

WSL Path Issues

• When building for Windows from WSL, use GOOS=windows
• Paths like C:\... should work on Windows builds
• Paths like /mnt/c/... work in WSL builds

Diagnostic Commands

Test your installation with these commands in Claude Desktop:

Show me the performance stats

Expected output shows operations per second, cache hit rate, and memory usage.

List the contents of [allowed path]

Should return directory listing without errors.

Log Levels

Use --log-level to control verbosity:

Level	Description
error	Only errors (recommended for production)
warn	Errors and warnings
info	Standard logging
debug	Verbose debugging information

Need More Help?

• Check the full documentation
• Report issues at GitHub Issues
• Include logs and configuration when reporting issues