Troubleshooting
Start with the operation ID and the authoritative provider record. A client timeout alone does not establish whether the command committed.
On this page
| Symptom | Check |
|---|---|
| Version conflict | Current stream head, expected version, and actor ownership. |
| Stale route | Route key, epoch, deployment fingerprint, silo admission, and promotion record. |
| Duplicate operation rejected | Canonical request identity and exact serialized event batch; a changed retry is invalid. |
| Projection lag | Persisted handoff or queue marker, consumer checkpoint, and application apply errors. |
| Pending external effect | Intent, provider availability, stable idempotency key, and terminal receipt. |
| Broker takeover blocked | SQL journal, KurrentDB stream evidence, trusted process roster, and predecessor state. |
Do not retry with a new operation ID until the original outcome is known. Do not clear projection markers, intent rows, or broker journals to make a dashboard green. Preserve logs with correlation IDs and route epochs while investigating; avoid logging payload secrets. After determining the authoritative outcome, follow the provider's recovery procedure and test the same failure in a staging environment.
See recovery, route authority, and the specific integration guide.
Example: Check the authoritative head
When a client times out, read the current stream head before deciding whether to retry. For a selected route, also inspect the operation receipt and route fence.
public static Task<(IEvent? Event, ulong Version)> RecoveryHead(IStore store) =>
store.ReadLastEvent("CounterActor-42");