---
title: Settings that must match the kernel
editUrl: https://github.com/Cratis/Chronicle/edit/main/Documentation/configuration/must-match-the-kernel.mdx
description: Client settings that have to agree with the Chronicle kernel's configuration, with the symptom of a mismatch and the page that explains each setting.
lastUpdated: 2026-11-20T00:00:00.000Z
---


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](/chronicle/connection-strings/server/), [Kernel ports](/chronicle/hosting/configuration/root-properties/) |
| 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](/chronicle/configuration/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](/chronicle/connection-strings/), [Authentication](/chronicle/hosting/configuration/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](/chronicle/configuration/tls/), [Kernel TLS](/chronicle/hosting/configuration/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](/chronicle/hosting/configuration/authentication/), [Production hosting](/chronicle/hosting/production/) |
| Cluster identity | Not set by clients | `clustering.clusterId`, `clustering.serviceId` identical on every node | Nodes with different values form separate clusters | [Clustering](/chronicle/hosting/configuration/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](/chronicle/migrations/validation/), [ChronicleOptions Reference](/chronicle/configuration/chronicle-options/#enableeventtypegenerationvalidation) |

## 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](/chronicle/configuration/chronicle-options/#eventstore) |
| 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](/chronicle/configuration/chronicle-options/#activationid-activationscope-and-lifecyclescope) |
| 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](/chronicle/configuration/chronicle-options/#namespacehttpheader) |
| 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](/chronicle/configuration/chronicle-options/#authentication) |
| 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](/chronicle/configuration/chronicle-options/#serverless) |
| 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](/chronicle/hosting/configuration/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](/chronicle/hosting/configuration/tls/) 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](/chronicle/hosting/production/) and [encryption certificate](/chronicle/hosting/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](/chronicle/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](/chronicle/hosting/configuration/federation/) for conditional secret requirements |

Environment variables replace each `:` with `__`. Client provider order and the options callback determine precedence; see [configuration flow](/chronicle/configuration/#how-client-configuration-flows). Kernel `chronicle.json` and environment sources are separate; see [hosting configuration](/chronicle/hosting/configuration/).

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