filepuff-mcp/docs/ERROR_CODES.md

MCP Filepuff Error Codes Reference

This document provides a comprehensive reference for all error codes that can be returned by mcp-filepuff, along with descriptions and remediation steps.

Error Code Structure

All errors in mcp-filepuff use structured error handling with the following components:

• Error Code: A numeric identifier (1000-1999) for programmatic handling
• Message: Human-readable description of the error
• Context: Additional key-value pairs providing error context
• Remediation: Suggested steps to resolve the error
• Cause: Underlying error (if wrapping another error)

Error Categories

Range	Category	Description
1000-1099	Search Errors	File search and ripgrep operations
1100-1199	Parser Errors	AST parsing and tree-sitter operations
1200-1299	LSP Errors	Language server protocol operations
1300-1399	Edit Errors	File editing operations
1400-1499	Query Errors	AST pattern matching operations
1500-1599	Config Errors	Configuration and validation
1900-1999	Internal Errors	Internal server errors

---

Search Errors (1000-1099)

1001 - ErrRipgrepNotFound

Description: The ripgrep (rg) binary is not found in the system PATH.

Common Causes:

• ripgrep is not installed
• ripgrep is not in PATH
• PATH environment variable not properly set

Remediation:

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows (Chocolatey)
choco install ripgrep

# Windows (Scoop)
scoop install ripgrep

---

1002 - ErrRipgrepTimeout

Description: Search operation exceeded the configured timeout limit.

Context Fields:

• pattern: The search pattern that timed out
• duration: How long the search ran before timing out

Common Causes:

• Search pattern too broad (e.g., . matching everything)
• Searching a very large directory tree
• Complex regex pattern causing backtracking

Remediation:

1. Use more specific search patterns
2. Narrow the search scope with paths parameter
3. Increase timeout via MCP_SEARCH_TIMEOUT environment variable:

   export MCP_SEARCH_TIMEOUT="2m"
   

---

1003 - ErrInvalidPattern

Description: The search pattern is invalid or malformed.

Context Fields:

• pattern: The invalid pattern
• error: Specific parsing error

Common Causes:

• Invalid regex syntax
• Unclosed brackets or parentheses
• Invalid escape sequences

Remediation:

1. Validate regex syntax at regex101.com
2. Escape special characters properly
3. Use regex: false for literal string searches

---

1004 - ErrSearchFailed

Description: General search operation failure.

Context Fields:

• error: Underlying error message

Common Causes:

• Permission denied on files/directories
• I/O errors
• ripgrep process crashed

Remediation:

1. Check file and directory permissions
2. Verify workspace path is accessible
3. Check system logs for I/O errors

---

1005 - ErrNoResults

Description: Search completed but found no matches.

Note: This is an informational code, not necessarily an error.

---

Parser Errors (1100-1199)

1101 - ErrParserNotFound

Description: No Tree-sitter parser is available for the requested language.

Context Fields:

• language: The unsupported language

Supported Languages:

• Go, TypeScript, JavaScript, Python, C, C++, HTML, Vue, Elixir, JSON, YAML

Remediation:

1. Use a supported language
2. Check file extension is correct

---

1102 - ErrParseFailed

Description: Tree-sitter failed to parse the file.

Context Fields:

• file: Path to the file
• language: Detected language
• error: Specific parsing error

Common Causes:

• File has syntax errors
• File encoding is not UTF-8
• Binary file detected

Remediation:

1. Fix syntax errors in the source file
2. Ensure file is valid UTF-8
3. Check file is not a binary

---

1103 - ErrInvalidLanguage

Description: The specified or detected language is not supported.

Context Fields:

• language: The unsupported language
• file: File path (if detected from extension)

Remediation:

• Use a file with a supported extension
• Supported: .go, .ts, .tsx, .js, .jsx, .py, .c, .h, .cpp, .hpp, .html, .vue, .ex, .exs, .json, .yaml, .yml

---

1104 - ErrFileTooBig

Description: File exceeds the maximum size limit for parsing.

Context Fields:

• file: Path to the file
• size_bytes: Actual file size
• limit_bytes: Maximum allowed size

Default Limit: 10 MB

Remediation:

1. Process smaller files
2. Increase limit via configuration:

   {
     "max_parse_size": 20971520
   }
   

---

1105 - ErrInvalidSyntax

Description: File contains syntax errors that prevent proper parsing.

Context Fields:

• file: Path to the file
• errors: List of syntax errors with locations

Remediation:

1. Fix syntax errors in the source file
2. Run language-specific linters/compilers to identify issues

---

LSP Errors (1200-1299)

1201 - ErrLSPServerNotFound

Description: The LSP server for the requested language is not installed or not in PATH.

Context Fields:

• language: The language needing LSP
• server: The expected server binary name

LSP Servers by Language:

Language	Server	Installation
Go	gopls	go install golang.org/x/tools/gopls@latest
TypeScript/JavaScript	typescript-language-server	npm install -g typescript-language-server typescript
Python	pylsp	pip install python-lsp-server
C/C++	clangd	Install via system package manager

Remediation: Install the appropriate language server for your language.

---

1202 - ErrLSPInitFailed

Description: LSP server failed to initialize.

Context Fields:

• language: The language
• command: The server command
• error: Specific initialization error

Common Causes:

• Workspace configuration issues
• Missing dependencies for the project
• LSP server crashed during startup

Remediation:

1. Check LSP server logs
2. Verify workspace has proper configuration files (go.mod, package.json, etc.)
3. Try running the LSP server manually to see errors

---

1203 - ErrLSPTimeout

Description: LSP operation exceeded timeout.

Context Fields:

• operation: The LSP method that timed out
• duration: How long the operation ran

Common Causes:

• LSP server indexing large project
• Complex type analysis
• Server deadlock

Remediation:

1. Wait for LSP server to complete initial indexing
2. Increase timeout via MCP_LSP_TIMEOUT:

   export MCP_LSP_TIMEOUT="10m"
   

3. Restart the MCP server to restart LSP servers

---

1204 - ErrLSPCommunication

Description: Communication error with LSP server.

Context Fields:

• error: Specific communication error

Common Causes:

• LSP server crashed
• Broken pipe (server terminated)
• Protocol version mismatch

Remediation:

1. Restart the MCP server
2. Update LSP server to latest version
3. Check for known issues with your LSP server version

---

1205 - ErrNoHoverInfo

Description: No hover information available at the requested position.

Note: Not all positions have hover information (e.g., whitespace, keywords).

---

1206 - ErrNoDefinition

Description: No definition found for the symbol at the requested position.

Common Causes:

• Position is not on a symbol
• Symbol is a built-in
• External dependency without source

---

1207 - ErrNoReferences

Description: No references found for the symbol.

Note: A symbol may have no references if unused.

---

Edit Errors (1300-1399)

1301 - ErrEditFailed

Description: General edit operation failure.

Context Fields:

• file: Path to the file
• operation: The edit operation attempted
• error: Specific error details

---

1302 - ErrInvalidEdit

Description: The edit request is malformed or invalid.

Context Fields:

• message: Specific validation failure

Common Causes:

• Missing required fields
• Invalid operation type
• Missing new_content for replace/insert

Valid Operations:

• replace - Replace selected content
• insert_before - Insert before selection
• insert_after - Insert after selection
• delete - Delete selected content

Remediation: Review the edit request and ensure all required fields are provided.

---

1303 - ErrFileNotFound

Description: The target file does not exist.

Context Fields:

• file: Path that was not found

Remediation:

1. Verify the file path is correct
2. Check for typos in the path
3. Ensure the file exists in the workspace

---

1304 - ErrFileNotReadable

Description: The file exists but cannot be read.

Context Fields:

• file: Path to the file
• error: System error details

Common Causes:

• Permission denied
• File locked by another process
• File is a directory

Remediation:

1. Check file permissions
2. Close other programs using the file
3. On macOS, ensure terminal has disk access

---

1305 - ErrFileNotWritable

Description: Cannot write to the file.

Context Fields:

• file: Path to the file
• error: System error details

Common Causes:

• Permission denied
• Read-only filesystem
• Disk full
• File locked

Remediation:

1. Check file and directory permissions
2. Verify disk space
3. Close other programs using the file

---

1306 - ErrNodeNotFound

Description: No AST node matches the selector criteria.

Context Fields:

• selector: Description of the selector criteria

Common Causes:

• Selector doesn't match any code
• Wrong node kind specified
• Name doesn't exist in file

Remediation:

1. Use file_read with include_ast: true to see available symbols
2. Verify selector criteria (kind, name, pattern, line)
3. Check spelling of symbol names

---

1307 - ErrValidationFailed

Description: Edit would produce invalid syntax.

Context Fields:

• file: Path to the file
• error: Syntax error details

Common Causes:

• new_content has syntax errors
• Edit breaks surrounding code structure

Remediation:

1. Validate new_content syntax independently
2. Use edit_preview to see the proposed changes
3. Ensure the edit maintains valid syntax

---

1308 - ErrInvalidSelection

Description: Selector matches multiple nodes or is ambiguous.

Context Fields:

• message: Details about the ambiguity

Common Causes:

• Text/pattern matches multiple locations
• Multiple functions with same name

Remediation:

1. Add selector_index to choose specific match
2. Add more selector criteria (kind, name, line)
3. Use line number to narrow selection

---

Query Errors (1400-1499)

1401 - ErrInvalidQuery

Description: The AST query is malformed.

Context Fields:

• query: The invalid query
• error: Specific parsing error

Remediation: Review query syntax. Valid patterns use:

• $NAME for single captures
• $$$ARGS for multiple items
• $_ for wildcards

---

1402 - ErrQueryTimeout

Description: AST query exceeded timeout.

Context Fields:

• query: The query that timed out
• duration: How long it ran

Remediation:

1. Use more specific patterns
2. Narrow search paths
3. Reduce max_results

---

1403 - ErrNoMatches

Description: Query executed successfully but found no matches.

Note: Informational, not necessarily an error.

---

1404 - ErrQueryCompile

Description: Failed to compile the query pattern.

Context Fields:

• pattern: The invalid pattern
• error: Compilation error

---

Config Errors (1500-1599)

1501 - ErrInvalidConfig

Description: Configuration file or value is invalid.

Context Fields:

• field: The invalid field
• value: The invalid value
• error: Specific validation error

Remediation: Review .mcp-filepuff.json configuration file syntax and values.

---

1502 - ErrPathNotAllowed

Description: Requested path is outside the workspace root.

Context Fields:

• path: The requested path
• workspace: The workspace root

Security Note: This prevents path traversal attacks.

Remediation:

1. Ensure all paths are within workspace
2. Don't use .. to escape workspace
3. Configure workspace root appropriately

---

1503 - ErrWorkspaceNotSet

Description: Workspace root is not configured.

Remediation: Start the server with -workspace flag:

mcp-filepuff -workspace /path/to/workspace

---

Internal Errors (1900-1999)

1900 - ErrInternal

Description: Unexpected internal error.

Context Fields:

• error: Error details
• stack: Stack trace (in debug mode)

Remediation:

1. Check server logs
2. Report issue if reproducible

---

1901 - ErrCacheFailed

Description: Cache operation failed.

Context Fields:

• operation: Cache operation that failed
• error: Specific error

---

1902 - ErrConcurrency

Description: Concurrency-related error (race condition, deadlock).

Context Fields:

• operation: Operation that failed
• error: Specific error

---

Common Error Scenarios

Scenario 1: New Project Setup

Symptoms: LSP features not working, errors like "LSP server not found"

Solution:

1. Install required language servers
2. Initialize project (e.g., go mod init, npm init)
3. Restart MCP server

Scenario 2: Edit Fails with Validation Error

Symptoms: Edit operation rejected with syntax error

Solution:

1. Use edit_preview first to see proposed changes
2. Validate new_content is syntactically correct
3. Check that surrounding code structure is maintained

Scenario 3: Search Returns Too Many Results

Symptoms: Search timeout or truncated results

Solution:

1. Use more specific patterns
2. Add file type filters: "file_types": ["go"]
3. Limit search paths
4. Set max_results limit

Scenario 4: File Access Errors

Symptoms: Permission denied, file not readable

Solution:

1. Check file permissions: ls -la <file>
2. On macOS, grant disk access to terminal
3. Close programs locking the file
4. Run server with appropriate user permissions

---

See Also

• API.md - Complete API reference
• PERFORMANCE.md - Performance tuning guide
• README.md - Getting started