Troubleshooting

Most “it’s not working” moments with Chronicle come down to a handful of causes. This page collects them. If your issue isn’t here, the Glossary and the feature guides go deeper.

My read model is empty or out of date

A read model is built by a projection that runs after events are appended — it is eventually consistent, not instant. A few things to check, in order:

• Did the events actually get appended? Look at the event sequence. No events in, no read model out.
• Did you give the projection time? Immediately after appending, the projection may not have processed yet. For tests, wait for the read model rather than asserting instantly.
• Does the projection map the events you appended? If the read model only handles BookAdded but you appended BookBorrowed, that event won’t change it.
• Is the property mapping right? AutoMap matches by name. A Title on the event maps to Title on the read model; a mismatch means the value silently doesn’t flow.

My projection isn’t picking up a change I made

After you change a projection, the existing read model still reflects the old logic. Rebuild it by replaying — re-running the projection over historical events. Because events are the source of truth, read models are disposable and safe to rebuild at any time.

My reactor ran twice (or sent a duplicate notification)

That’s expected — reactors can run more than once for the same event during replay or recovery. The fix is not to prevent it but to make the reactor idempotent: record that the side effect happened and skip it if it already did. See Reacting to events.

My reactor throws and the stream seems stuck

If a reactor throws, the failing event source partition pauses until the problem is resolved — by design, so it doesn’t silently skip events. Fix the underlying error (and make the reactor resilient), and processing resumes.

A constraint is rejecting an append I expected to succeed

Constraints are enforced as events are appended — a uniqueness constraint, for example, rejects a second event that would violate it. Check which constraint fired and whether the value really is a duplicate within its scope (remember namespaces isolate data per tenant).

I can’t connect to the Chronicle kernel

• Confirm the kernel is running — if you scaffolded from a template, docker compose up -d and check the container is healthy.
• Confirm the client URL matches the kernel’s address and port.
• Confirm your storage (MongoDB by default) is reachable from the kernel.

See Connection strings and Get started.

Events look wrong after a schema change

When an event type’s shape changes over time, use event type migrations to evolve old events to the new shape rather than mutating history. Events are immutable — you migrate how they’re read, you don’t edit what was written.