コンテンツにスキップ
日本語

Sharding overview

このコンテンツはまだ日本語訳がありません。

Cluster sharding is the framework’s answer to “I have a few million entities, each needing its own actor, scattered across N nodes.” Examples: per-user sessions, per-IoT-device controllers, per-order coordinators, per-game-room actors.

The user gives the framework a way to extract an entity ID from each message; the framework hashes that ID to a shard; the coordinator decides which node hosts that shard; the node’s local region routes to that shard, which spawns the entity actor on demand. When nodes come and go, the coordinator rebalances shards across the new topology.

cluster of 3 nodes

node-1 region

node-2 region

node-3 region

shards 1-33

shards 34-66

shards 67-100

entities for keys
hashing to those shards

entities for keys
hashing to those shards

entities for keys
hashing to those shards

Each entity is one actor, on one node, at a time — just like a singleton, but scaled to N entities at once. Failover happens automatically: when a node leaves, its shards move elsewhere and the entities re-spawn there.

import { match } from 'ts-pattern';
import { Actor } from 'actor-ts';
import { Cluster, ClusterBootstrapOptions, StartShardingOptions } from 'actor-ts/cluster';
type AddCommand = { entityId: string; kind: 'add'; sku: string };
type ViewCommand = { entityId: string; kind: 'view'; replyTo: ActorRef<Cart> };
type CartCommand = AddCommand | ViewCommand;
class CartActor extends Actor<CartCommand> {
private items: string[] = [];
override onReceive(command: CartCommand): void {
match(command)
.with({ kind: 'add' }, (c) => this.onAdd(c))
.with({ kind: 'view' }, (c) => this.onView(c))
.exhaustive();
}
private onAdd(command: AddCommand): void { this.items.push(command.sku); }
private onView(command: ViewCommand): void { command.replyTo.tell({ items: this.items }); }
}
// Setup — one-line cluster + sharding entry point:
const { system, cluster } = await Cluster.bootstrap(ClusterBootstrapOptions.create('my-app'));
const startShardingOptions = StartShardingOptions.create<CartCommand>().withExtractEntityId((message) => message.entityId);
const cartRegion = cluster.sharding.start('cart', CartActor,
startShardingOptions);
// Usage — `tell` to the region, with entity ID inside the message:
cartRegion.tell({ entityId: 'user-42', kind: 'add', sku: 'book-1' });
cartRegion.tell({ entityId: 'user-42', kind: 'view', replyTo: ... });
// ^^^^^^^^^^
// Same ID → same entity actor, every time, regardless of node.

cluster.sharding.start() accepts several calling shapes — pick whichever fits the entity. The shortest is to let the entity declare its own identity, which means neither the type name nor the entity-id extractor is repeated at the call site:

class CartActor extends Actor<CartCommand> {
static readonly shard = ShardKey.of<CartCommand>('cart', (command) => command.entityId);
// ...
}
const cartRegion = cluster.sharding.start(CartActor);
const cart = cluster.sharding.entityRefFor(CartActor, 'user-42');

A ShardKey’s identity is its typeName alone; the extractor rides along so the declaring class is the single source of truth, but a node that only looks entities up can name the same type with ShardKey.of<CartCommand>('cart') and no extractor. An extractEntityId passed in options overrides the one on the key.

The remaining shapes are unchanged:

// 1. Class shorthand:
const startShardingOptions = StartShardingOptions.create<CartCommand>().withExtractEntityId((m) => m.entityId);
cluster.sharding.start('cart', CartActor, startShardingOptions);
// 2. Factory shorthand — when the entity needs constructor args:
const startSharding2Options = StartShardingOptions.create<CartCommand>().withExtractEntityId((m) => m.entityId);
cluster.sharding.start('cart', () => new CartActor(deps),
startSharding2Options);
// 3. Full-form — every setting via the builder:
const startSharding3Options = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((m) => m.entityId)
.withNumShards(16)
.withRole('cart-host');
cluster.sharding.start(
startSharding3Options,
);

cluster.sharding is a memoised facade — repeated reads return the same ClusterSharding instance. The explicit form ClusterSharding.get(system, cluster) still works and resolves to the same object; reach for it only when you need to reference the class from outside a cluster handle.

The cartRegion is a single ActorRef from the caller’s perspective. Behind the scenes:

  1. The region computes a shard from entityId (default: hash to one of 64 shards).
  2. It asks the coordinator “who owns this shard?”
  3. If the owner is this node, it spawns the entity (if not already present) and forwards the message.
  4. If the owner is another node, it forwards over the cluster transport to that node’s region, which does the same.
ActorRole
RegionOne per node. Routes messages to the right shard’s owner, and decides when local entities — and shards left empty — passivate.
ShardOne per shard hosted here, a child of the region. Owns the entity actors: spawns them, stops them, buffers for one on its way out. Goes away itself once it has stood empty for its window, and comes back with the next message.
CoordinatorOne per cluster (singleton, on the leader). Decides which node owns each shard. Handles rebalancing on membership changes, and on a region shutting down.
EntityOne per entityId. A child of its shard, on whichever node currently owns the shard the ID hashes to.

That gives entities a real path — /system/cluster/sharding/region-counter/shard-7/entity-user-42 — which is what makes a shard addressable at all. See introspection for listing shards and getting refs to them.

The region is the subject of this page; the coordinator’s decisions have pages of their own — see the allocation strategy and rebalance for the mechanics.

An entity nearly always needs the id it was routed by — to name its journal stream, its pub/sub topic, or a row in someone else’s database. It reads that off itself:

class CartEntity extends Actor<CartCommand> {
override preStart(): void {
this.log.info(`cart ${this.entityId} woke up in shard ${this.entity.shardId}`);
}
}
this.entityIdThe value extractEntityId returned, unchanged.
this.entityThe same id plus typeName and shardId.
this.context.entityThe Option form — None when this actor is not an entity. Both getters above throw instead.

The commonest use is a per-entity persistenceId, which is what gives a sharded PersistentActor one event stream per entity rather than one per type:

class CartEntity extends PersistentActor<CartCommand, CartEvent, CartState> {
override get persistenceId(): string { return `cart-${this.entityId}`; }
}

The identity is set on the entity and nowhere else — an entity’s own children get None, so this.context.entity.nonEmpty answers “am I the entity?”. Pass the id down explicitly to a child that needs it.

To exercise an entity on its own, hand it an identity directly instead of standing up a cluster around it:

import { ActorOptions } from 'actor-ts';
const cartOptions = ActorOptions.create()
.withEntity({ entityId: 'user-42', typeName: 'cart', shardId: 3 });
const cart = system.spawn(CartEntity, 'cart-under-test', cartOptions);

.../shard-7/entity-user-42 looks like it carries the id, and for simple ids slicing off the entity- prefix does work. It is not the id, though: actor names have a restricted alphabet, so the shard escapes anything a name cannot carry when it names the child — a code unit outside [A-Za-z0-9_-.@:+] becomes ~ plus four hex digits, so user/42 is named entity-user~002F42.

The escape is injective: two different ids never land on one name. That is a correctness property, not a nicety — a shared name means the second entity spawns under a name already taken, and the resulting throw kills the shard along with every other entity living in it.

What it is not is a second way to spell the id. Nothing decodes a path segment, deliberately, and the escape is not part of the API. The path is a label; entityId is the value.

ShardingOptionsType<TMessage> — the fields you’ll most often touch:

type ShardingOptionsType<TMessage> = {
typeName: string;
entityActor: ActorClassOrFactory<TMessage>;
entityOptions?: ActorOptions<TMessage>;
extractEntityId: (message: TMessage) => string;
extractEntityMessage?: (message: TMessage) => unknown;
numShards?: number; // default 64
role?: string; // restrict to nodes carrying this role
proxy?: boolean; // route-only, no local entities
rememberEntities?: boolean; // re-spawn entities on failover (#)
passivationIdleMs?: number; // auto-stop idle entities, default 5 min
shardPassivationIdleMs?: number; // auto-stop empty shards, follows the above
maxEntities?: number; // resident-entity cap, per type per node
passivationReplacement?: EntityReplacementPolicy; // which entity the cap gives up
};
FieldWhat it controls
typeNameA string identifying this sharded type. Different types can coexist in the same cluster (cart, session, order).
extractEntityId(message)Pull the entity ID from a message. This is the key that gets hashed to a shard.
extractEntityMessage(message)(Optional) If the message envelope contains routing info plus a payload, this strips the envelope before the entity sees it. Defaults to the message as-is.
numShardsHow many shards the entity space is divided into. 64 is fine for most clusters; bump to 1000 for very large clusters (>50 nodes). Must be the same on every node that starts or proxies this type — see below.
roleOnly members with this role host shards of this type. Useful for placing compute-heavy entities on dedicated nodes. Also settable node-wide as actor-ts.sharding.role — see placement from the config file.
proxyThis node forwards messages to the region but never hosts entities locally. Used for client nodes in an asymmetric cluster.
rememberEntitiesPersist the set of active entity IDs. After a coordinator failover (or full cluster restart), those IDs are spawned eagerly so messages don’t have to recreate the entire fleet.
passivationIdleMsStop an entity after this much idle time. Frees memory; next message for the same ID re-creates the entity. Defaults to 5 minutes; 0 disables it.
shardPassivationIdleMsStop a shard after it has stood empty this long. Unset it follows passivationIdleMs; 0 keeps empty shards resident while entities still passivate.
maxEntitiesHow many entities of this type may be resident on this node. When exceeded, one is passivated to make room. 0 (the default) means no cap. Not node-wide: two started types each get the whole number.
passivationReplacementWhich resident entity the cap gives up — 'least-recently-used' (default), 'segmented-least-recently-used' or 'least-frequently-used'. Inert while maxEntities is 0; see choosing what a full node gives up.

The defaults are sensible for small clusters. For production, you usually want rememberEntities: true and a passivationIdleMs matched to your traffic pattern.

role is the one placement option with a HOCON key, because which role hosts a type is uniform across a deployment:

actor-ts.sharding.role = "backend"

It applies to every sharded type started on the node without its own withRole, and an explicit withRole still wins — the usual explicit options > HOCON > built-in defaults order, per field.

What it does not do is give a node the role. A node’s own roles are a separate setting, and a per-node one where sharding.role is the same everywhere: ClusterOptions.withRoles in code, or actor-ts.cluster.roles in the node’s config, usually filled from its environment:

actor-ts.cluster.roles = [ ${?NODE_ROLE} ]
const clusterOptions = ClusterOptions.create()
.withHost('10.0.0.7')
.withPort(2551)
.withRoles(['backend']);

Set only sharding.role and no member matches: the coordinator finds no candidate, nothing is ever allocated, and every message for the type piles up in the region’s routing buffer. It is not silent — the coordinator warns once with the role, the number of registered regions it excluded and both places a node declares its roles — but it is a warning, not a failure to start, so read it.

proxy has no key on purpose: it is per-node topology, a second start disagreeing about it throws, and a proxy = on shared by every node would leave nothing hosting anything.

A shard id is hash(entityId) % numShards, and every node computes it for itself. Two nodes with different counts therefore put the same entity id in different shards, each ends up owning the shard its own arithmetic produced, and both run a live instance of the entity — at shard-6/entity-user-7 and shard-50/entity-user-7, paths that never collide. For a persistent entity that means two writers on one persistenceId.

So the count travels in the region’s registration and the coordinator refuses a region that disagrees with it:

ERROR [sharding] the coordinator refused to register region 'counter':
numShards must match across the cluster, but this node is configured
with 32 and the coordinator governs the type with 64.

A refused region stays up and keeps buffering — it is never allocated a shard, so the misconfiguration is a stall with an error next to it rather than a silent split. Fix the count and restart the node.

A region that was already hosting shards gives them up on the spot. That case is not exotic: it is what a rolling deploy produces the moment leadership reaches an already-updated node. The region was accepted by the previous leader, so it holds real shards and real entities, and the new coordinator refuses it. It stops each of those shards — a proper stop, so the entities beneath them run their postStop and a persistent one flushes — and drops the ownership in the same step, which is what turns the refusal into a stall on this node instead of one half of a split. Nothing comes back until the counts agree; the buffered traffic waits.

This is asynchronous by nature: a region registers after start(...) returns, retries until the coordinator answers, and re-registers on every leader change. There is no call to throw from, which is why the verdict arrives as a log line rather than an exception.

Two consequences worth knowing:

  • A proxy node counts. startProxy hashes exactly like a hosting region, so it needs the same numShards; starting one from a bare key in a cluster that does not use the default gets it refused.
  • Setting actor-ts.sharding.number-of-shards in a config file shared by every node is the least error-prone way to keep them in step.

The refusal also survives a coordinatorStateStore. That store lets an incoming leader skip the reallocation storm by adopting its predecessor’s allocation map, and every shard id in such a snapshot was produced under the writing coordinator’s count — so a snapshot is now stamped with that count and one taken under a different (or, for a snapshot written before the stamp existed, an unstated) count is dropped whole, with a WARN naming both numbers. A region the coordinator has already refused is skipped even when the snapshot names it. Without either check the load path put the refused regions straight back into the placement pool: a rolling deploy that changes the count would re-establish the split routing through the snapshot rather than through the registration handshake, which is the one place the counts are compared.

Dropping a snapshot costs one reallocation pass, which is exactly what every cluster without a store already does on a leader change — and the next allocation change under the new leader writes a stamped snapshot, so it happens once.

Starting the same type twice on one node — start() after startProxy(), or the reverse — throws. The second call used to return the region the first one made, so a node that asked for a hosting region got the proxy, whose placeholder entity factory throws the moment a shard lands locally.

Five of these are also HOCON keys — number-of-shards, remember-entities, passivation-idle, shard-passivation-idle and max-entities — as are the coordinator’s rebalance-interval and hand-off-timeout, and the whole passivation sub-block that decides which entity the cap gives up. They set the node-wide baseline for every sharded type and sit under whatever start(...) passes explicitly, so a per-type value in the builder still wins. See Configuration.

actor-ts.sharding {
number-of-shards = 128
passivation-idle = 2 minutes
max-entities = 50000
passivation.replacement = segmented-least-recently-used
}

Passivation stops an idle entity to free memory; the next message for the same ID re-creates it. However it is triggered, the region buffers messages that arrive while the entity is stopping and replays them to the fresh incarnation, so nothing is lost.

The default idle window is 5 minutes. Set passivationIdleMs — in code or via actor-ts.sharding.passivation-idle — to change it, or 0 to switch it off and keep every entity resident for the lifetime of its node.

Automatic — when passivationIdleMs elapses with no traffic, or maxEntities is exceeded (whichever entity the replacement policy names is evicted), the entity is stopped. Nothing is sent to the entity and no acknowledgment is involved. The decision is the region’s, because only it sees traffic across every shard on this node — which is why maxEntities is a cap per type per node, not a per-shard one — and the shard that owns the entity carries it out.

Manual (graceful) — an entity asks to be passivated by sending a Passivate to its parent, which is its shard. Passivate carries a stop-message that gets forwarded back to the entity, so the entity decides exactly when and how it shuts down (finish in-flight work, flush state, then terminate). Using PoisonPill as the stop-message terminates the entity as soon as it comes back:

import { match } from 'ts-pattern';
import { PoisonPill, Actor } from 'actor-ts';
import { Passivate } from 'actor-ts/cluster';
type AddCommand = { entityId: string; kind: 'add'; sku: string };
type CheckoutCommand = { entityId: string; kind: 'checkout' };
type CartCommand = AddCommand | CheckoutCommand;
class CartActor extends Actor<CartCommand> {
private items: string[] = [];
override onReceive(command: CartCommand): void {
match(command)
.with({ kind: 'add' }, (c) => this.onAdd(c))
.with({ kind: 'checkout' }, () => this.onCheckout())
.exhaustive();
}
private onAdd(command: AddCommand): void {
this.items.push(command.sku);
}
// Done with this cart — ask the region to passivate us.
private onCheckout(): void {
this.context.parent.forEach((parent) =>
parent.tell(new Passivate(PoisonPill.instance, this.self), this.self));
}
}

The stop-message is a request: the entity decides when to act on it. If it never does, it never terminates — and its slot stays charged to maxEntities for the lifetime of the node. passivationStopTimeoutMs (actor-ts.sharding.passivation.stop-timeout) is the backstop for that: after it, the shard stops the entity outright, the same way a region-driven passivation does.

It is off by default (0, wait forever), and it is off because the cooperative contract is the point. An entity mid-drain — a long flush, a slow final write — is entitled to take as long as the drain takes, and a forced stop there abandons the flush; only you know how long yours may legitimately run. Set it where an entity that never acts on the message would be a bug worth containing. It is independent of maxEntities: a positive value arms it with or without a cap.

maxEntities says how many entities stay resident; passivationReplacement says which one leaves when a new one arrives. Every knob here is inert while maxEntities is 0, which is the default.

The default policy, 'least-recently-used', has one blind spot: recency cannot tell touched once, ever from touched constantly until a moment ago. So a pass over a large cold key space — a nightly export, a crawler, a backfill — evicts your working set one entity at a time and leaves the node holding ids nothing will ask for again. Two options fix that, and they compose:

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
.withMaxEntities(50_000)
// Probation for an entity seen once, protected for one seen again; eviction
// takes from probation, so a scan can only ever displace another scan.
.withPassivationReplacement('segmented-least-recently-used')
.withPassivationSegmentedProtectedProportion(0.8)
// A small window in front of the policy, so the entity judged on admission is
// never the one a message is waiting on.
.withPassivationAdmissionWindowProportion(0.01)
// …and what does the judging: a compact sketch of how often each id has been
// seen, which remembers ids the node no longer holds.
.withPassivationAdmissionFilter('frequency-sketch');

'least-frequently-used' is the third policy — fewest accesses loses, with counts halved periodically so the ranking follows recent traffic rather than a lifetime total. It suits a working set that is stable but not recent, such as a device fleet reporting on a slow cycle.

The filter needs a window: a region cannot refuse the entity a message has just arrived for, so 'frequency-sketch' with passivationAdmissionWindowProportion: 0 is rejected at start(...) rather than silently doing nothing. All five knobs are also HOCON keys under actor-ts.sharding.passivation.

Passivating every entity in a shard used to leave the shard itself behind — a live actor holding an empty map. Nothing stopped it short of a rebalance, and because entity IDs spread over the hash space, a long-running node eventually touched every shard and kept all of them. With numShards = 64 that is 64 idle actors with nothing in them.

So a shard that has stood empty for shardPassivationIdleMs is stopped as well. The region keeps ownership — only the actor goes — so the shard stays routable and the next message for it re-creates the shard and the entity together, with no coordinator round trip. Unset, the window follows passivationIdleMs, which is usually what you want: a shard is empty precisely because its entities went idle.

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
.withPassivationIdleMs(120_000)
// Shards are cheap to keep and cost a respawn to lose — outliving their
// entities by a while is a reasonable trade on a busy node.
.withShardPassivationIdleMs(600_000);

Set shardPassivationIdleMs: 0 to keep empty shards resident while entities still passivate. The region and the coordinator are unaffected either way — they run for the lifetime of the node.

Only an empty shard is ever stopped, so there is no entity state at stake, and messages that arrive while a shard is stopping are buffered and replayed exactly as they are for an entity. “Empty” is the shard’s own answer, not the region’s guess: the region asks a shard it counts empty to stop, and the shard stops only if it still has nothing — no entity the message just ahead of the request created, no remembered entity a recovery batch just started, no entity backing off. Otherwise it stays, the region routes to it again, and a later sweep asks again. A shard ref stays valid across the gap too — see introspection, where ShardInfo also reports a resident flag that tells a passivated shard apart from one that is merely empty.

An entity that cannot do its work — a poison message, a store that is down, a start that throws — fails again every time it is re-created. Three paths re-create it, and they behave differently:

  1. An entity inside its shard. The shard supervises its entities like any parent: a failed entity is restarted in place, immediately, up to ten times a minute. That budget is the shard’s, so every entity in the shard draws on the same one. Past it the entity is stopped, and the shard re-creates it only after a wait, entity-restart-backoff — see an entity that keeps stopping.
  2. A shard inside its region. A failure the shard does not absorb — an entity whose own strategy escalates, or a fault in the shard itself — reaches the region, which stops the shard rather than restarting it. Every entity under the shard stops with it, and the region forgets them.
  3. A shard coming back. A shard that stopped without the region asking — anything but a hand-off, a passivation or a release — is re-created after a wait, shard-failure-backoff, not on the next message. Once the wait is over, the region re-creates it, replays what waited for it and, under rememberEntities, asks the coordinator for the shard’s entities, so they come back without any traffic.

While the shard is down the region keeps its ownership: nothing is re-homed, and the coordinator still places the shard here. Messages for it wait in the region buffer against buffer-size — past the cap the newest is dead-lettered with its sender — and are delivered, with their senders, once the shard is back. That covers what the region routes after the shard has died. What it had already routed into a shard that fails — case 2 above — and that has not reached its entity yet is lost with the shard: the region learns of the failure only from the shard’s death, and what is still queued in a stopping shard or its entities goes to dead letters, each message with its sender. So a message sent to a healthy entity just as its sibling’s failure escalates can be lost. The restart in place that stopping replaced kept the shard’s mailbox, but tore down every entity under the shard without the region hearing of it. Nothing else brings the shard back early: not a message, not a shard ref from shardRefFor() (it relays through the region until then), not a repeated placement or a re-shipped registry. A message told to a shard ref that is not for an entity — GetShardStats, say — goes to dead letters.

Each death in a row doubles the wait, from min up to max, spread by random-factor either way; a shard that went reset-after without failing since it came back starts again at min when it next dies — a passivation in between is not a failure, so a cold shard re-created by a poison message is judged by how long it had been healthy, not by the few milliseconds of its new incarnation. At the shipped values a shard that fails once in a while is back after about 200 ms, and one that fails on every start is re-created about every ten seconds instead of thousands of times a second:

actor-ts.sharding.shard-failure-backoff {
min = 200ms # the first wait; must be > 0
max = 10s # the doubling stops here
random-factor = 0.2 # each wait spread by up to 20 % either way
reset-after = 60s # no failure for this long, and the next death waits min
}

The builder takes the same four, in milliseconds and as a fraction:

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
.withRememberEntities(true)
// The store behind these entities takes seconds to fail over: wait at
// least one, and never more than a minute.
.withShardFailureBackoffMinMs(1_000)
.withShardFailureBackoffMaxMs(60_000);

What this means for an entity’s own supervisorStrategy, set through entityOptions:

  • Its restarts are immediate and come out of the shard’s budget. One entity in a restart loop can spend the allowance its siblings needed, and nothing slows it down until that budget runs out; from then on the entity restart backoff below does.
  • A strategy that escalates hands the failure to the whole shard. Every sibling stops with it, and all of them wait out the shard’s backoff. Escalate only for failures that mean the shard itself cannot go on.

Past the restart budget an entity is stopped, and the next message for it used to create a fresh one: an entity failing on every message was re-created per message — thirty instances for thirty messages — and each one opened its recovery against whatever was failing it. Now the shard keeps it down for a while first, entity-restart-backoff, and the wait grows while it keeps stopping.

A shard cannot see why an entity stopped, so it backs off every stop it did not ask for: a failure past the budget, a start or a recovery that keeps failing, a recovery failure the entity swallowed, a lost lease, a plain stopSelf. The one stop it asks for is a passivation — the entity’s own Passivate, or the region’s idle and capacity passivation — and an entity stopped that way comes back on the next message at once. So stop an entity on purpose with Passivate, not with stopSelf.

The restarts inside the budget stay immediate: a SupervisorStrategy has no delay to give, and this is the wait after them. Meanwhile:

  • Messages for the entity are held, each with its sender, and handed over in order once it is back. The hold is capped at buffer-size per shard, across the shard’s entities; past it the newest is dead-lettered with its sender, with one warning per episode. A shard that stops while it holds messages dead-letters them the same way.
  • The shard stays up for its wait. A shard whose entity is backing off is not empty, even though the entity is not running: the empty-shard sweep leaves it alone until the wait is over and nothing is held, so a shardPassivationIdleMs shorter than the wait neither drops what is held nor starts the backoff over.
  • A start waits too. A StartEntity for the entity — told to a shard ref, say — re-creates it when its wait ends, not at once. Once the wait is over with nothing held, the next message creates the entity at once.
  • The region still hears of the stop, as before: under rememberEntities the entity is recorded as stopped, and it is not revived until a message comes for it.

The waits double and reset the way the shard’s do: an entity that went reset-after without stopping unasked since it came back starts again at min, and a passivation in between is not a failure. At the shipped values an entity failing on every message is re-created about every ten seconds: thirty messages at 5 ms now make twelve instances — the first, its ten restarts inside the budget, and one when the wait ends — where they used to make thirty.

actor-ts.sharding.entity-restart-backoff {
min = 200ms # the first wait after the restart budget; must be > 0
max = 10s # the doubling stops here
random-factor = 0.2 # each wait spread by up to 20 % either way
reset-after = 60s # no unasked stop for this long, and the next one waits min
}

The builder takes the same four:

const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((command) => command.entityId)
// A cart's recovery reads a store that takes seconds to fail over:
// give it one before the first retry, and at most half a minute.
.withEntityRestartBackoffMinMs(1_000)
.withEntityRestartBackoffMaxMs(30_000);

When the cluster topology changes (a node joins or leaves) — or a region stops, which tells the coordinator on its way down — the coordinator runs a rebalance pass:

  1. Compute the new shard-to-node assignment from the active allocation strategy (default: hash mod regions).
  2. For each shard that moved, tell the old region to hand off the shard.
  3. The old region stops its entities (which may persist their state), tells the coordinator “handoff complete,” and stops routing for that shard.
  4. The new region spawns entities for that shard on demand as messages arrive.

The handoff isn’t instant — buffered messages wait for the “handoff complete” signal before being forwarded to the new owner. This avoids messages racing past a half-moved entity.

See Rebalance for the full protocol.

cluster.leave() hands this node’s shards off before it tells anyone it is going, and waits for that:

  1. Every region the node started stops its shards and their entities. Each entity finishes the message it is handling — a persistent entity’s write lands — and runs postStop; then the region tells the coordinator it is gone, which re-homes its shards.
  2. The node’s coordinators stop after its regions, so a coordinator still active on a leaving leader hears its own regions go and re-homes their shards at once — remembered entities restart on their new home without being sent anything.
  3. Only then does the node move to leaving and tell its peers.

So no peer re-homes a shard while it still runs here: a shard never has two live homes, and a persistent entity never a second writer. The wait is bounded by each type’s hand-off-timeout. A region that has not stopped by then — an entity stuck in its handler holds it up — is told to stop at once, a warning names it, and the leave goes on without it; until it has gone, that one entity may still run when its new home starts it.

The coordinated-shutdown pipeline does the same in its cluster-sharding-shutdown-region phase, ahead of cluster-leave. A node its own downing decision took out, or one that gave its join up, leaves at once instead and stops its sharding beside the departure: the peers that downed it do not wait for a hand-off.

Once leave() resolves, the regions’ and coordinators’ names are free again, so a re-join on the same ActorSystem starts the same types through the new cluster’s sharding. The left cluster’s facade refuses to start anything: actors started through it would be bound to a cluster that is gone.

A message on its way to the leaving node while the hand-off runs is not carried over to the new home — it is lost, as it is to any region that stops. The hand-off moves shards, not messages in flight.

Sharded entities are subject to the same restart semantics as any other actor — when an entity moves to a new node, the new instance starts with a clean slate.

For state that should survive:

  • PersistentActor — the entity persists events to a journal; on a fresh node, it replays the journal at startup. See PersistentActor.
  • DurableStateActor — simpler: persist the current state snapshot; restore on restart. See DurableState.
  • DistributedData — for state that should be readable from any node (not just the entity’s current host), use a CRDT in the DD replicator instead.

Without one of these, sharding gives you placement and routing, not durability.

The coordinator keeps where each shard lives in memory, and a new leader starts from an empty map that it rebuilds from the regions’ registrations. actor-ts.sharding.persist-coordinator-state = on (or withPersistCoordinatorState()) keeps that map in the persistence extension’s journal instead, so a new leader — often a node that has just restarted, since the leader is the lowest address — starts from the map the previous one last wrote (#1188):

actor-ts.sharding {
persist-coordinator-state = on
coordinator-state-load-timeout = 10s
}

The journal has to be one database for the whole cluster — the next leader reads what the previous one wrote — so a node-local journal on a node that expects remote peers is refused when the type starts. Only the latest map is kept: each save compacts the one before it, and a save from a coordinator whose view of the stream is stale fails instead of overwriting.

Placement still waits for the regions’ own claims after a leader change: the map can lag the last allocation, and only a region’s registration proves what it really runs. What the map adds is the regions themselves — a new leader asks each one it names to register — and the homes of shards nobody has claimed yet. A new leader waits at most coordinator-state-load-timeout for the map to load and then places shards without it.

Three good fits:

  1. Per-user / per-tenant state that’s too much for one node to hold but doesn’t need to be readable from everywhere simultaneously.
  2. Per-entity workflows — sagas, order processing, long-running coordinators — that benefit from per-key serialization.
  3. Hotspots that follow keys — a streaming pipeline where each user’s events should be processed in order on a single actor.

The ClusterSharding and ShardRegion API references cover the full surface, including the per-node region actor.