MSSQL MCP Server

Databases
MIT License
Overview InspectNew Schema Related Servers Reviews Score
# Error Handling Documentation

This document details the error handling system in the MSSQL MCP Server, including error categories, codes, and troubleshooting guidelines.

## Error Response Format

All errors follow a consistent format:

```typescript
{
  code: string;          // Unique error identifier
  message: string;       // Human-readable error description
  details?: any;         // Additional error context
  cause?: string;        // Original error that caused this error
  suggestions?: string[]; // Recommended solutions
}
```

## Error Categories

### 1. Connection Errors (CONNECTION_*)

#### CONNECTION_ERROR
- **Description**: General connection failure
- **Possible Causes**:
  - Network connectivity issues
  - Invalid credentials
  - Server unavailable
- **Solutions**:
  - Verify network connectivity
  - Check credentials
  - Confirm server status
  - Check firewall settings

#### CONNECTION_TIMEOUT
- **Description**: Connection attempt timed out
- **Possible Causes**:
  - Network latency
  - Server overload
  - Firewall blocking
- **Solutions**:
  - Increase timeout settings
  - Check network performance
  - Verify firewall rules

#### CONNECTION_CLOSED
- **Description**: Connection unexpectedly closed
- **Possible Causes**:
  - Server restart
  - Network interruption
  - Connection pool timeout
- **Solutions**:
  - Implement retry logic
  - Check server logs
  - Adjust pool settings

### 2. Query Errors (QUERY_*)

#### INVALID_QUERY
- **Description**: SQL syntax error
- **Possible Causes**:
  - Syntax mistakes
  - Invalid table/column names
  - Unsupported SQL features
- **Solutions**:
  - Verify SQL syntax
  - Check object names
  - Review SQL Server version compatibility

#### PARAMETER_MISMATCH
- **Description**: Parameter validation failure
- **Possible Causes**:
  - Missing parameters
  - Invalid parameter types
  - Parameter name mismatch
- **Solutions**:
  - Check parameter names
  - Verify parameter types
  - Ensure all required parameters are provided

#### QUERY_TIMEOUT
- **Description**: Query execution timeout
- **Possible Causes**:
  - Complex query
  - Server load
  - Missing indexes
- **Solutions**:
  - Optimize query
  - Add appropriate indexes
  - Increase timeout setting
  - Consider query pagination

### 3. Permission Errors (PERMISSION_*)

#### PERMISSION_DENIED
- **Description**: Insufficient privileges
- **Possible Causes**:
  - Missing user permissions
  - Object-level restrictions
  - Server-level restrictions
- **Solutions**:
  - Review user permissions
  - Check object permissions
  - Request necessary access

#### LOGIN_FAILED
- **Description**: Authentication failure
- **Possible Causes**:
  - Invalid credentials
  - Account locked
  - Password expired
- **Solutions**:
  - Verify credentials
  - Check account status
  - Update password if needed

### 4. Resource Errors (RESOURCE_*)

#### DATABASE_NOT_FOUND
- **Description**: Database does not exist
- **Possible Causes**:
  - Database name typo
  - Database not created
  - Database deleted
- **Solutions**:
  - Verify database name
  - Check database existence
  - Create database if needed

#### TABLE_NOT_FOUND
- **Description**: Table does not exist
- **Possible Causes**:
  - Table name typo
  - Wrong schema
  - Table deleted
- **Solutions**:
  - Verify table name
  - Check schema name
  - Confirm table existence

#### SCHEMA_NOT_FOUND
- **Description**: Schema does not exist
- **Possible Causes**:
  - Schema name typo
  - Schema not created
  - Schema deleted
- **Solutions**:
  - Verify schema name
  - Check schema existence
  - Create schema if needed

### 5. Validation Errors (VALIDATION_*)

#### INVALID_INPUT
- **Description**: Input validation failure
- **Possible Causes**:
  - Invalid data types
  - Value out of range
  - Format mismatch
- **Solutions**:
  - Check input types
  - Verify value ranges
  - Format data correctly

#### CONSTRAINT_VIOLATION
- **Description**: Database constraint violation
- **Possible Causes**:
  - Unique constraint violation
  - Foreign key constraint violation
  - Check constraint violation
- **Solutions**:
  - Check unique constraints
  - Verify foreign key relationships
  - Validate check constraints

## Error Handling Best Practices

1. **Logging**
   - Log all errors with context
   - Include timestamp and correlation ID
   - Maintain different log levels
   - Implement log rotation

2. **Recovery**
   - Implement retry logic for transient errors
   - Use exponential backoff
   - Set maximum retry attempts
   - Handle cleanup after errors

3. **User Communication**
   - Provide clear error messages
   - Include actionable solutions
   - Hide sensitive information
   - Use appropriate error codes

4. **Prevention**
   - Validate inputs early
   - Check permissions proactively
   - Monitor resource usage
   - Implement timeouts

## Troubleshooting Guide

1. **Connection Issues**
   - Verify network connectivity
   - Check firewall settings
   - Confirm server status
   - Review connection string
   - Check SSL/TLS settings

2. **Query Problems**
   - Review query syntax
   - Check execution plan
   - Verify parameter types
   - Monitor query performance
   - Check for deadlocks

3. **Permission Problems**
   - Review user permissions
   - Check object permissions
   - Verify login status
   - Review security policies
   - Check for permission inheritance

4. **Resource Issues**
   - Monitor server resources
   - Check connection pool
   - Review memory usage
   - Monitor disk space
   - Check CPU utilization

## Monitoring and Alerting

1. **Key Metrics**
   - Error rate
   - Connection failures
   - Query timeouts
   - Permission denials
   - Resource exhaustion

2. **Alert Thresholds**
   - Error rate spike
   - Connection pool exhaustion
   - High query timeout rate
   - Repeated permission failures
   - Resource usage limits

3. **Response Plans**
   - Error investigation
   - Resource scaling
   - Permission updates
   - Query optimization
   - Infrastructure updates