65 lines
2.1 KiB
Markdown
65 lines
2.1 KiB
Markdown
# 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.
|
|
- If WAL growth is the issue, run `CheckpointMode.Truncate` (or `Restart`) instead of `Full`.
|
|
- If foreground latency is a concern, schedule `CheckpointMode.Passive` retries and use `Truncate` during maintenance windows.
|
|
|
|
## 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).
|