# Troubleshooting

This guide provides solutions for common issues you might encounter when using AWS Logs MCP.

## AWS Connection Issues

### Unable to Connect to AWS Services

**Symptoms:**
- "Failed to connect to AWS services" error messages
- `AccessDenied` or `UnauthorizedException` errors
- Connection tests fail

**Possible Causes and Solutions:**

1. **Invalid AWS Credentials**
   - Verify your AWS credentials are correct
   - Run `aws sts get-caller-identity` to test credentials
   - Check environment variables are properly set

2. **Insufficient Permissions**
   - Ensure your IAM user/role has the required permissions
   - Add missing permissions to your IAM policy
   - Check for resource-level restrictions in your IAM policy

3. **Region Configuration**
   - Verify you're connecting to the correct AWS region
   - Ensure the region contains the logs/events you're looking for
   - Set the `AWS_REGION` environment variable correctly

4. **Network Issues**
   - Check network connectivity to AWS services
   - Verify firewall rules allow outbound connections
   - If using a VPC, ensure endpoints or NAT gateway are configured properly

### Specific AWS Service Errors

**CloudWatch Logs Errors:**

| Error | Possible Solution |
|-------|-------------------|
| `ResourceNotFoundException` | Verify log group/stream names exist and are spelled correctly |
| `InvalidParameterException` | Check parameter format (especially timestamps) |
| `LimitExceededException` | Reduce request size or implement backoff/retry logic |

**CloudTrail Errors:**

| Error | Possible Solution |
|-------|-------------------|
| `InvalidLookupAttributesException` | Verify lookup attributes are valid |
| `InvalidTimeRangeException` | Ensure time range is valid (max 90 days) |
| `OperationNotPermittedException` | Verify CloudTrail is enabled in the account |

## Server Issues

### Server Won't Start

**Symptoms:**
- Server crashes during startup
- Error logs showing startup failures

**Possible Causes and Solutions:**

1. **Port Conflicts**
   - Another application might be using the configured port
   - Change the port in your configuration or environment variables
   - Use `lsof -i :3000` to check for processes using the port

2. **Configuration Errors**
   - Check your `.env` file for missing or invalid values
   - Ensure all required environment variables are set
   - Verify configuration file syntax

3. **Dependency Issues**
   - Ensure all dependencies are installed: `pnpm install`
   - Check for compatibility issues with Node.js version
   - Look for error messages related to specific dependencies

### Performance Problems

**Symptoms:**
- Slow response times
- Timeouts for large queries

**Possible Causes and Solutions:**

1. **Large Result Sets**
   - Reduce the time range in your queries
   - Add more specific filters to limit results
   - Adjust the `MAX_LOG_ENTRIES` setting

2. **Resource Constraints**
   - Increase memory allocation for the application
   - Monitor CPU usage and scale up if needed
   - Consider using a larger instance or container size

3. **Network Latency**
   - Deploy the server closer to your AWS region
   - Use direct VPC endpoints for AWS services
   - Implement caching for frequently accessed data

## Client Connection Issues

### Client Cannot Connect to Server

**Symptoms:**
- Connection refused errors
- Timeout errors
- SSE connection fails to establish

**Possible Causes and Solutions:**

1. **Server Not Running**
   - Verify the server is running: `curl http://localhost:3000/health`
   - Check server logs for crash information
   - Restart the server

2. **Network Configuration**
   - Ensure the client can reach the server network
   - Check firewall rules and network ACLs
   - Verify proxy configurations

3. **CORS Issues**
   - If connecting from a browser, check for CORS errors
   - Add the client origin to the server's allowed origins
   - Use appropriate CORS headers

### Tool Invocation Errors

**Symptoms:**
- Tool invocation fails
- Validation errors
- Unexpected tool behavior

**Possible Causes and Solutions:**

1. **Invalid Parameters**
   - Check parameter types and formats
   - Review tool documentation for required parameters
   - Ensure date/time formats are correct

2. **Tool Registration Issues**
   - Verify the tool is properly registered
   - Check for typos in the tool name
   - Ensure you're connected to the correct server

## Logging and Debugging

### Enable Debug Logging

To get more detailed logs:

1. Set the log level to debug:
   ```
   LOG_LEVEL=debug
   ```

2. Look for specific error contexts in the logs:
   - AWS service errors will include service and operation information
   - Validation errors will include details about invalid parameters
   - Connection errors will include AWS endpoint information

### Use Server Health Check

The health check endpoint provides valuable diagnostic information:

```bash
curl http://localhost:3000/health
```

This returns information about:
- Server status
- AWS connectivity
- Resource usage
- Version information

## Requesting Help

If you're unable to resolve an issue:

1. Collect the following information:
   - Server logs with debug level enabled
   - AWS credential information (without actual secret values)
   - Environment configuration (Node.js version, OS, etc.)
   - Exact steps to reproduce the problem

2. Open an issue on GitHub with:
   - A clear description of the problem
   - Steps to reproduce
   - Expected vs. actual behavior
   - Relevant logs and configuration