Skip to content

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

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.

  • 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 clusterId and serviceId and the same cluster database.