# Troubleshooting

## Build And Test Failures

### Symptom
`dotnet build` or `dotnet test` fails locally or in CI.

### Checks
1. Verify .NET 10 SDK is installed.
2. Run `dotnet restore`.
3. Run `dotnet format --verify-no-changes`.
4. Re-run tests with `dotnet test CBDD.slnx -c Release`.

### Resolution
- Fix reported compile/test failures before merge.
- For flaky tests, isolate affected test class and open an issue with reproduction details.

## Data File And Recovery Issues

### Symptom
Database startup fails or recovery path throws WAL/storage errors.

### Checks
1. Capture exact exception and stack trace.
2. Reproduce with storage/recovery-focused tests.
3. Validate rollback path from [`deployment.md`](deployment.md#rollback-procedure).

### Resolution
- Pin consumers to last known-good package.
- Apply fix and add regression coverage in recovery/transaction tests.

## Query And Index Issues

### Symptom
Unexpected query performance or incorrect query results.

### Checks
1. Verify relevant indexes are configured for query predicates.
2. Reproduce with test cases in `tests/CBDD.Tests` for query/index modules.
3. Validate behavior for scan fallback and expression translation.

### Resolution
- Add or adjust index definitions and query tests.
- Document any changed query semantics in release notes.

## Source Generation Issues

### Symptom
Generated mappers missing or serialization behavior differs from expectations.

### Checks
1. Verify entity attributes and accessibility are valid for source generation.
2. Build solution to regenerate mapper output.
3. Validate related tests in source generator test coverage.

### Resolution
- Update entity annotations or generator logic.
- Add focused regression tests for unsupported pattern handling.

## Escalation

If troubleshooting steps do not resolve the issue, follow incident escalation in [`runbook.md`](runbook.md).