Common Issues

Common issues and solutions you may encounter when using SmartRAG.

Build Issues

Warning

Always run a clean solution first to resolve build errors.

NuGet Package Error

# Clean solution
dotnet clean
dotnet restore
dotnet build

Dependency Conflict

<PackageReference Include="SmartRAG" Version="1.1.0" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0" />

Runtime Issues

Configuration

Most runtime issues are related to configuration problems.

AI Provider Not Configured

// Ensure proper configuration
services.AddSmartRAG(options =>
{
    options.AIProvider = AIProvider.Anthropic;
    options.StorageProvider = StorageProvider.Qdrant;
    options.ApiKey = "your-api-key";
});

API Key Issues

# Set environment variable
export SMARTRAG_API_KEY=your-api-key

# Or use appsettings.json
{
  "SmartRAG": {
    "ApiKey": "your-api-key"
  }
}

Performance Issues

Optimization

Performance can be improved with proper configuration.

Slow Document Processing

// Optimize chunk size
services.AddSmartRAG(options =>
{
    options.ChunkSize = 500; // Smaller chunks for faster processing
    options.ChunkOverlap = 100;
});

Memory Usage

// Use appropriate storage provider
services.AddSmartRAG(options =>
{
    options.StorageProvider = StorageProvider.Redis; // For high memory usage
    // or
    options.StorageProvider = StorageProvider.Qdrant; // For large datasets
});

Debugging

Tools and techniques to help you debug SmartRAG applications.

Enable Logging

// Configure logging
builder.Logging.AddConsole();
builder.Logging.SetMinimumLevel(LogLevel.Debug);

// In your service
private readonly ILogger<DocumentService> _logger;

public async Task<Document> UploadDocumentAsync(IFormFile file)
{
    _logger.LogInformation("Uploading document: {FileName}", file.FileName);
    // ... implementation
}

Exception Handling

try
{
    var document = await _documentService.UploadDocumentAsync(file);
    return Ok(document);
}
catch (ArgumentException ex)
{
    _logger.LogError(ex, "Invalid file format");
    return BadRequest("Invalid file format");
}
catch (HttpRequestException ex)
{
    _logger.LogError(ex, "AI provider error");
    return StatusCode(503, "Service temporarily unavailable");
}
catch (Exception ex)
{
    _logger.LogError(ex, "Unexpected error");
    return StatusCode(500, "Internal server error");
}

Testing

How to test your SmartRAG implementation.

Unit Testing

[Test]
public async Task UploadDocument_ValidFile_ReturnsDocument()
{
    // Arrange
    var mockFile = new Mock<IFormFile>();
    var service = new DocumentService(mockLogger.Object);
    
    // Act
    var result = await service.UploadDocumentAsync(mockFile.Object);
    
    // Assert
    Assert.IsNotNull(result);
    Assert.IsNotEmpty(result.Id);
}

Integration Testing

[Test]
public async Task SearchDocuments_ReturnsRelevantResults()
{
    // Arrange
    var testQuery = "test query";
    
    // Act
    var results = await _documentService.SearchDocumentsAsync(testQuery);
    
    // Assert
    Assert.IsNotNull(results);
    Assert.IsTrue(results.Any());
}

Getting Help

If you're still having issues, here's how to get help.

GitHub Issues

Report bugs and request features on GitHub.

Open Issue

Email Support

Get direct help via email.

Contact

Before Asking for Help

Checklist

Check the Getting Started guide
Review the Configuration documentation
Search existing GitHub Issues
Include error messages and configuration details

Prevention

Best practices to avoid common issues.

Configuration Best Practices

API Keys

Never hardcode API keys. Use environment variables or secure configuration.

Storage

Choose the right storage provider for your use case.

Error Handling

Implement proper error handling and logging.

Performance

Monitor performance and optimize chunk sizes.

Troubleshooting