Settings that must match the kernel
A client and the kernel it connects to are configured separately. Most settings are independent, but the ones below only work when both sides agree. When a connection fails in a way the error message does not explain, check this table first.
| Setting | Client side | Kernel side | If they differ | Details |
|---|---|---|---|---|
| Client gRPC port | Connection-string server port; defaults to 35000. Outside a container, use its published host port: 45000:35000 means chronicle://localhost:45000 |
Main Chronicle listener port, default 35000, or its reachable proxy/published endpoint |
The client cannot reach gRPC on the wrong endpoint. Do not use Orleans silo/gateway ports, dedicated health/federation ports or the external OAuth authority’s port. Built-in OAuth and health may share the main listener, but their routes are not the client gRPC endpoint | Server address, Kernel ports |
| gRPC message size | MaxReceiveMessageSize, MaxSendMessageSize (100 MiB each) |
maxReceiveMessageSize (100 MiB) |
A message larger than the receiving side’s limit is refused with a gRPC ResourceExhausted status. Raise the receiver’s limit, then check the sender’s |
gRPC Message Size |
| Client credentials | Credentials in the connection string; built-in credentials are for local development only | The development image accepts the development credentials. A production kernel does not | A client using the development credentials against a production kernel is refused | Connection strings, Authentication |
| TLS and certificate trust | Tls options and skipTlsValidation, disableTls, caCertificatePath, certificatePath in the connection string |
tls section: certificate and enabled |
A client that uses TLS cannot connect to a kernel with TLS disabled, and the other way around. With validation on, the client must trust the CA of the kernel certificate | TLS, Kernel TLS |
| External token authority | The authority the client gets its tokens from | Authentication:Authority: the issuer URL of an external identity provider, not the kernel’s own address. Leave it empty to use the kernel’s built-in token issuer; setting it to the kernel’s URL turns that issuer off. It must be HTTPS when the kernel runs without TLS |
Tokens issued by another authority fail validation | Authentication, Production hosting |
| Cluster identity | Not set by clients | clustering.clusterId, clustering.serviceId identical on every node |
Nodes with different values form separate clusters | Clustering |
| Event type generation validation | EnableEventTypeGenerationValidation |
Honored only by the development kernel. A production kernel always validates strictly | Setting it to false has no effect against a production kernel |
Validation, ChronicleOptions Reference |
Required settings and startup validation
Section titled “Required settings and startup validation”Client settings mostly have defaults. These requirements apply only in the stated mode. Kernel settings belong to the server’s configuration, not the client’s, despite sharing the Cratis:Chronicle prefix.
| Side and condition | Setting to supply | Failure or diagnostic | Example / remedy |
|---|---|---|---|
| Hosted client, only if no configured or derived store name is usable | Cratis:Chronicle:EventStore |
Options validation names the key, environment variable and callback remedy | Set Cratis__Chronicle__EventStore=orders; see name derivation |
| Client, lifecycle handlers using application activation scope | Cratis:Chronicle:ActivationId |
ActivationIdRequired if the host supplies no logical activation identity |
Supply a stable rollout identity or explicitly select ActivationScope=PerProcess; see lifecycle settings |
| ASP.NET Core, when overriding the header default | Cratis:Chronicle:NamespaceHttpHeader |
Required-property validation rejects an empty value | Keep the default or name a trusted header; see namespace resolution |
| Client, hashed event-source tracing | Cratis:Chronicle:Telemetry:EventSourceIdHashKey |
Telemetry:EventSourceIdHashKey must be at least 32 characters when Hashed is used |
Supply a deployment-specific key from a secret provider |
| Client, external OAuth | Authentication:Authority or Authentication:TokenEndpoint under Cratis:Chronicle and explicit client credentials |
URLs must be absolute HTTPS without user info; Scope alone fails; implicit development credentials are refused | See external authority example |
| Client, serverless | Stable ProgramIdentifier; nonzero Serverless:DeploymentGeneration with Deploy outside Development; explicit acknowledgement for OnColdStart there |
Validation names the relevant Cratis:Chronicle:* key; timeout must be positive and unauthenticated receiver mode requires opt-in |
See serverless defaults and conditions |
| Kernel, persistent storage | Storage:ConnectionDetails or Storage:ConnectionDetailsFile under Cratis:Chronicle |
Storage:ConnectionDetails is required; InMemory is exempt. Unrecognized connection formats also require Storage:Type |
Set Cratis__Chronicle__Storage__ConnectionDetailsFile=/run/secrets/storage; do not set inline and file forms together. See storage |
| Production kernel, default TLS listener | Cratis:Chronicle:Tls:CertificatePath and any required password |
No implicit production certificate; load/configuration failure stops startup | Mount a PFX; TLS configuration covers private h2c behind a terminating proxy instead |
| Production kernel, internal OAuth enabled | Cratis:Chronicle:EncryptionCertificate:CertificatePath and any required password |
Missing/unreadable/private-key-less certificate stops startup; disabling internal OAuth removes this startup requirement, not encryption needs on use | See production requirements and encryption certificate |
| Kernel, named sinks | Entries in Cratis:Chronicle:Sinks:Configurations |
Unknown/missing type, connection details or Neo4j server produces InvalidSinkConfiguration; defaults must name a compatible sink |
See named sinks |
| Kernel, hosted federation | Federation listener, public endpoint and externally provisioned key-encryption-key material as applicable | Disabled by default; authority/enrollment refuse to operate without protected internal secrets | See hosted federation for conditional secret requirements |
Environment variables replace each : with __. Client provider order and the options callback determine precedence; see configuration flow. Kernel chronicle.json and environment sources are separate; see hosting configuration.
Check the pair
Section titled “Check the pair”- Change message limits on both sides. Raising only the sender’s limit moves the failure to the receiver.
- Use explicit credentials in every environment except local development.
- Enable certificate validation in production and give the client a CA file for private certificate authorities.
- Give every node of a cluster the same
clusterIdandserviceIdand the same cluster database.