dotnet-cqrs/docs/troubleshooting

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

General framework errors:

• Handler not found
• Registration errors
• DI configuration issues

Validation Errors

FluentValidation issues:

• Validator not found
• RFC 7807 not working
• Google Rich Error Model issues

gRPC Errors

gRPC-specific problems:

• Connection failures
• Code generation issues
• Status codes and error handling

Event Streaming Errors

Event streaming issues:

• Stream not found
• Offset errors
• Consumer group problems

Consumer Lag

Diagnosing and fixing consumer lag:

• Identifying lag causes
• Scaling strategies
• Performance optimization

FAQ

Frequently asked questions

Quick Fixes

Handler Not Found

Error:

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

Solution:

// Make sure handler is registered
builder.Services.AddCommand<CreateOrderCommand, int, CreateOrderCommandHandler>();

Validation Not Working

Error: Validation not triggering, invalid data accepted.

Solution:

// 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

// 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:

# 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

// 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

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

Check Registration

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

Monitor Health

// 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
2. Check Best Practices
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
• Best Practices
• Observability