# MCP Server Error Response Formats
## Overview
The Memory MCP server implements proper JSON-RPC 2.0 error handling to ensure clients always receive valid responses, even when internal errors occur.
## Error Response Format
All error responses follow the JSON-RPC 2.0 specification:
```json
{
"jsonrpc": "2.0",
"id": "<request_id>",
"error": {
"code": <error_code>,
"message": "<error_message>",
"data": {
"details": "<detailed_error_description>"
}
}
}
```
## Error Codes
### Standard JSON-RPC Error Codes
- `-32700`: Parse error - Invalid JSON received
- `-32600`: Invalid request - The JSON sent is not a valid Request object
- `-32601`: Method not found - The method does not exist or is not available
- `-32602`: Invalid params - Invalid method parameter(s)
- `-32603`: Internal error - Internal JSON-RPC error
### MCP-Specific Error Codes
- `-32000`: Tool execution failed - A tool call failed during execution
## Error Scenarios
### 1. JSON Serialization Failures
When the server fails to serialize response data to JSON:
```json
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Internal error",
"data": {
"details": "Response serialization failed: <specific_error>"
}
}
}
```
### 2. Invalid Method Calls
When a client requests a non-existent method:
```json
{
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32601,
"message": "Method not found",
"data": {
"method": "unknown_method"
}
}
}
```
### 3. Tool Execution Failures
When a tool call fails during execution:
```json
{
"jsonrpc": "2.0",
"id": 3,
"error": {
"code": -32000,
"message": "Tool execution failed",
"data": {
"details": "<tool_specific_error>"
}
}
}
```
## Client Handling
Clients should always check for the presence of `error` vs `result` in responses:
```javascript
if (response.error) {
// Handle error based on error.code
switch (response.error.code) {
case -32603:
// Internal error - retry or report
break;
case -32601:
// Method not found - check method name
break;
// ... handle other codes
}
} else {
// Process successful result
processResult(response.result);
}
```
## Server Stability
The server is designed to never panic due to JSON serialization failures. All `serde_json::to_value()` calls are wrapped in proper error handling that returns structured JSON-RPC error responses instead of crashing.
## Troubleshooting
### Common Issues
1. **"failed parse server response"**: This should no longer occur as the server always returns valid JSON. If it happens, check client-side JSON parsing.
2. **Error code -32603**: Indicates internal server error. Check server logs for details in the `data.details` field.
3. **Malformed responses**: Should not occur. If they do, it's a bug in the server that needs immediate fixing.
### Debugging
Enable debug logging to see detailed error information:
```bash
RUST_LOG=debug cargo run --bin do-memory-mcp-server
```
Look for log messages like:
```
ERROR Failed to serialize initialize response: <error_details>
```
## Troubleshooting Guide
### Problem: "failed parse server response"
**Symptoms:**
- Client receives responses that can't be parsed as JSON
- JSON parsing errors in client applications
- Intermittent connection issues
**Root Causes:**
1. **Server panic** (should no longer occur after fix)
2. **Client-side JSON parsing issues**
3. **Network corruption**
4. **Memory corruption in server**
**Solutions:**
1. **Check server logs** for panic messages or serialization errors
2. **Verify client JSON parser** can handle valid JSON-RPC responses
3. **Test with simple requests** to isolate the issue
4. **Check network connectivity** and proxy configurations
### Problem: Error code -32603 (Internal error)
**Symptoms:**
- Server returns internal error responses
- Operations fail unexpectedly
- Logs show serialization failures
**Possible Causes:**
1. **Memory pressure** causing JSON allocation failures
2. **Complex data structures** that can't be serialized
3. **Custom types** without proper Serialize implementation
4. **Large response payloads** exceeding memory limits
**Solutions:**
1. **Check memory usage** and system resources
2. **Review data structures** being returned by tools
3. **Implement pagination** for large result sets
4. **Add response size limits** if needed
### Problem: Tool execution failures (-32000)
**Symptoms:**
- Tool calls return error responses
- Specific tool operations fail
- Error details in `data.details` field
**Common Issues:**
1. **Code execution errors** in sandbox
2. **Invalid tool parameters**
3. **Resource limits exceeded**
4. **Security violations**
**Solutions:**
1. **Check tool parameters** are correctly formatted
2. **Review sandbox logs** for execution details
3. **Verify resource limits** are appropriate
4. **Test tools individually** to isolate issues
### Problem: Method not found (-32601)
**Symptoms:**
- "Method not found" error responses
- Tool calls fail with unknown method
**Causes:**
1. **Typo in method name**
2. **Outdated client** calling deprecated methods
3. **Server configuration issues**
**Solutions:**
1. **Verify method names** match server capabilities
2. **Check server logs** for available tools
3. **Update client** to use correct method names
### Monitoring and Alerting
**Key Metrics to Monitor:**
- Error response rate (should be < 1%)
- Serialization failure count (should be 0)
- Tool execution success rate
- Response time percentiles
**Alert Conditions:**
- Error rate > 5% for 5 minutes
- Any serialization failures
- Tool success rate < 95%
### Performance Considerations
**Response Size Limits:**
- Keep responses under 1MB to prevent serialization issues
- Implement pagination for large datasets
- Compress responses if supported by client
**Timeout Handling:**
- Set appropriate timeouts for long-running operations
- Return timeout errors instead of hanging
- Implement request cancellation
### Best Practices
1. **Always check for errors** in client code before processing results
2. **Log error details** on both client and server for debugging
3. **Implement retry logic** for transient errors
4. **Monitor error rates** and alert on anomalies
5. **Keep error messages** descriptive but not verbose
6. **Use appropriate HTTP status codes** when applicable