CBDD/docs/troubleshooting.md

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.

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.