# Troubleshooting

Common issues and solutions for Svrnty.CQRS.

## Overview

This section covers common problems, error messages, and solutions for working with Svrnty.CQRS.

## Common Issues

### [Common Errors](common-errors.md)

General framework errors:
- Handler not found
- Registration errors
- DI configuration issues

### [Validation Errors](validation-errors.md)

FluentValidation issues:
- Validator not found
- RFC 7807 not working
- Google Rich Error Model issues

### [gRPC Errors](grpc-errors.md)

gRPC-specific problems:
- Connection failures
- Code generation issues
- Status codes and error handling

### [Event Streaming Errors](event-streaming-errors.md)

Event streaming issues:
- Stream not found
- Offset errors
- Consumer group problems

### [Consumer Lag](consumer-lag.md)

Diagnosing and fixing consumer lag:
- Identifying lag causes
- Scaling strategies
- Performance optimization

### [FAQ](faq.md)

Frequently asked questions

## Quick Fixes

### Handler Not Found

**Error:**
```
System.InvalidOperationException: No service for type 'ICommandHandler<CreateOrderCommand, int>' has been registered.
```

**Solution:**
```csharp
// Make sure handler is registered
builder.Services.AddCommand<CreateOrderCommand, int, CreateOrderCommandHandler>();
```

### Validation Not Working

**Error:**
Validation not triggering, invalid data accepted.

**Solution:**
```csharp
// Register validator
builder.Services.AddTransient<IValidator<CreateOrderCommand>, CreateOrderCommandValidator>();

// Ensure FluentValidation package installed
// dotnet add package Svrnty.CQRS.FluentValidation
```

### gRPC Connection Failed

**Error:**
```
Grpc.Core.RpcException: Status(StatusCode="Unavailable", Detail="failed to connect to all addresses")
```

**Solutions:**
1. Check server is running
2. Verify port number
3. Check HTTP vs HTTPS
4. Verify firewall settings

```csharp
// Correct address format
var channel = GrpcChannel.ForAddress("https://localhost:5001");

// For development (self-signed cert)
var handler = new HttpClientHandler
{
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
};

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions
{
    HttpHandler = handler
});
```

### Database Connection Failed

**Error:**
```
Npgsql.NpgsqlException: Connection refused
```

**Solutions:**
```bash
# Check PostgreSQL is running
docker ps | grep postgres

# Test connection
psql -h localhost -U postgres -d eventstore

# Verify connection string
Host=localhost;Database=eventstore;Username=postgres;Password=postgres
```

### Consumer Lag Growing

**Symptoms:**
- Consumer offset falling behind stream head
- Processing slower than publishing

**Solutions:**
1. Increase consumer count (horizontal scaling)
2. Increase batch size
3. Optimize event handlers
4. Check database performance

```csharp
// Increase batch size
options.BatchSize = 1000;  // From 100

// Use AfterBatch commit strategy
options.CommitStrategy = OffsetCommitStrategy.AfterBatch;

// Add more consumers
// Deploy more instances to consumer group
```

## Diagnostic Tools

### Enable Debug Logging

```csharp
builder.Logging.AddFilter("Svrnty.CQRS", LogLevel.Debug);
builder.Logging.AddFilter("Grpc", LogLevel.Debug);
```

### Check Registration

```csharp
// Verify handler is registered
var handler = serviceProvider.GetService<ICommandHandler<CreateOrderCommand, int>>();
if (handler == null)
{
    Console.WriteLine("Handler not registered!");
}
```

### Monitor Health

```csharp
// Add health checks
builder.Services.AddHealthChecks()
    .AddCheck<StreamHealthCheck>("event-streams");

app.MapHealthChecks("/health");

// Check: curl http://localhost:5000/health
```

## Getting Help

### Check Documentation

1. Review [Getting Started](../getting-started/README.md)
2. Check [Best Practices](../best-practices/README.md)
3. Review relevant integration guide (HTTP/gRPC)

### Collect Information

Before asking for help, gather:
- Error messages (full stack trace)
- Code samples (minimal reproducible example)
- Package versions
- Framework version (.NET version)
- Environment (development/production)

### Ask for Help

- GitHub Issues: https://github.com/svrnty/dotnet-cqrs/issues
- Include diagnostic information
- Provide minimal reproducible example

## See Also

- [Getting Started](../getting-started/README.md)
- [Best Practices](../best-practices/README.md)
- [Observability](../observability/README.md)