XState release notes, breaking changes, and upgrade notes.
Actor-based state management and orchestration StackPulse turns upstream changelogs into scannable summaries with risky changes, deprecations, migration notes, and source links.
Callback, event observable, listener, subscription, and effect event stream actors now process events they send to a parent within their own transitions. Inspection reports outgoing events on the source transition, and subscribers receive a snapshot notification for that transition. The release also exports utilities for inspecting typed actor failures while preserving the original Effect Cause.
affected
XState Effect users working with actor event transitions, inspection, subscriber snapshots, or typed failures are affected.
release_signals
+Export `causeFromError` and `UnwrapEffectFailure` for inspecting typed actor failures while preserving the original Effect Cause.
+Callback, event observable, listener, subscription, and `createEffectEventStreamLogic` actors process events sent to a parent in their own transitions.
This release updates the codemod package alongside xstate@6.0.0-beta.3. Its notes describe a breaking `xstate/fsm` transition API change, add eventless `always` transitions, and provide a codemod transform to update inline FSM configurations.
affected
Users of `xstate/fsm` configurations or transition functions that use string targets or return strings are affected.
action
Apply the `string-targets` codemod to inline FSM configurations and manually review separately stored configurations and transition functions.
release_signals
-In `xstate/fsm`, `on` and `always` transition targets must now be objects, such as `{ target: 'ready' }`, rather than strings. Transition functions must return an object or `undefined`; `initial: 'idle'` remains unchanged.
This beta adds eventless `always` transitions to `xstate/fsm` and changes how callback, observable, listener, and subscription actors process and report events sent to a parent. It also fixes event ordering for delayed events and prevents targetless reentering transitions from running entry behavior.
affected
Users of `xstate/fsm` with string transition targets or string-returning transition functions must update those configurations; users of the affected actor types receive changed event processing and inspection/subscriber notifications.
action
Update FSM transition targets to object form and review separately stored configurations and transition functions before upgrading.
release_signals
-`xstate/fsm` now requires object transition targets for `on` and `always`; for example, replace `on: { GO: 'ready' }` with `on: { GO: { target: 'ready' } }`.
Serialized snapshot and effect-descriptor fields that began with `$` or `_` have been renamed to storage-compatible names, addressing restrictions in databases such as Convex and MongoDB. Restore functions continue to accept snapshots with the old field names, but newly serialized snapshots use the new names and omit private counter fields from `snapshot.toJSON()`.
affected
Users persisting or consuming serialized snapshots, systemTransition snapshots, effect descriptors, or @xstate/test traces are affected; restore functions continue to read both old and new snapshot shapes.
action
Update persisted-snapshot validation schemas and any consumers that depend on the renamed serialized fields.
release_signals
-Serialized field names changed: `$actor`, `$error`, `$stateNode`, and `$systemMapper` now use `@` prefixes; `_nextTimerId`, `_nextActorIds`, and `_stateInputs` no longer use underscore prefixes. Consumers expecting the old serialized shape, including schema validators, must account for the new names.
Serialized snapshots and effect-related descriptors now use field names without `$` or `_` prefixes, improving compatibility with persistence stores that reject those names. The release also exports `sendAndAwait` from the main entrypoint and updates effect actor observer ordering and stop behavior to align with `createActor`.
affected
Users persisting or validating XState snapshots and consumers of serialized effect descriptors are affected by the renamed fields; restore functions continue to accept snapshots with the old names.
action
Update snapshot-validation schemas to the new field names before relying on newly serialized snapshots.
This release updates the codemod package’s XState dependency to 6.0.0-beta.2, which changes serialized snapshot and descriptor field names to avoid `$` and `_` prefixes that some databases reject. Restore APIs continue to accept snapshots written with the old names, but new snapshots use the new names and schemas that validate persisted snapshots must be updated accordingly.
affected
Users persisting or validating XState snapshots, system transition snapshots, or effect descriptors are affected by the serialized field-name changes.
action
Update persisted-snapshot validation schemas to use the new field names; no snapshot rewrite is required for restoration because the documented restore APIs accept both shapes.
release_signals
-Serialized output now uses `@actor`, `@error`, `@stateNode`, and `@systemMapper` instead of the corresponding `$`-prefixed names, and uses `nextTimerId`, `nextActorIds`, and `stateInputs` instead of underscore-prefixed names where applicable. New persisted snapshot schemas, including those using `machineVersions`, must use the new names.
This beta changes serialized snapshot and related output field names to avoid `$` and `_` prefixes, while retaining compatibility when restoring snapshots written by beta.1. It also adds durable checkpoints that preserve transition progress and queued root events, alongside fixes for FSM behavior, typing, snapshot retention, and inspector event reporting.
affected
Users persisting or validating snapshots and consumers of serialized actor references or effect descriptors are affected by the renamed fields; durable execution users can use the new checkpoint format to preserve queued events across restoration.
action
Update persisted-snapshot validation schemas to the new field names and use `durable.checkpoint(snapshot)` when checkpointing durable executions that need to preserve queued root events.
release_signals
xstate@5.33.4mediumfeatureNov 7, 2026
xstate@5.33.4
This patch fixes TypeScript narrowing for `assertEvent` when event types are generic or have union-valued `type` fields. Partial wildcard descriptors now also preserve the bare prefix event in narrowed types, aligning the types with runtime behavior.
affected
TypeScript users relying on `assertEvent`, `ExtractEvent`, or partial wildcard transition event inference may see more accurate event types.
This prerelease expands the XState codemod with migration transforms and reports for v5-to-v6 changes, including action shapes, lifecycle event keys, and ignored machine implementations. It also adds JSON migration reporting and commands to record and compare machine behavior, alongside updates for xstate@6.0.0-beta.1.
affected
XState users migrating machines from v5 to v6 can use the new transforms and behavior-comparison commands to automate supported changes and identify manual work.
action
For v5-to-v6 migrations, try the new `baseline`, `migrate --json`, and `verify` workflow and review any reported manual sites.
release_signals
+Added `migrate --json` to emit a JSON report, including manual migration sites and details; exits with code 2 when manual migration is needed.
The release strengthens TypeScript validation for machine definitions created with `setup().createMachine(...)`. Unknown transition targets, including targets returned by transition functions, are now reported as type errors; dynamic (non-literal) string targets remain accepted.
affected
TypeScript users defining machines with `setup().createMachine(...)` are affected, especially if their transition targets refer to nonexistent states.
action
Check `setup().createMachine(...)` transition targets for typos or references to nonexistent states if new type errors appear.
release_signals
+Type checking now rejects unknown transition targets in `setup().createMachine(...)`, including targets returned from transition functions.
The Vue hooks `useActorRef`, `useActor`, and `useMachine` can now accept an already-created actor, including one restored with `restoreActor`. The `snapshot` option is removed; XState v6 has entered beta, with no further breaking changes planned for `@public` APIs and possible changes to `@experimental` APIs.
affected
Vue users who restore or otherwise create actors before passing them to these hooks are affected; users of `@experimental` APIs should note those APIs may still change.
action
If using the removed `snapshot` option, migrate to `restoreActor` and pass the restored actor to the hook.
release_signals
-The hooks’ `snapshot` option is removed. Restore an actor with `restoreActor` from `xstate/persist` and pass the actor to a hook instead.
This prerelease announces that XState v6 has entered beta. The notes say no further breaking changes are planned for APIs tagged `@public`; `@experimental` APIs may still change.
affected
Users of XState v6 are affected, particularly those relying on APIs tagged `@experimental`, which may still change.
The Svelte hooks `useActorRef`, `useActor`, and `useMachine` now accept an already-created actor, including one restored with `restoreActor`. The `snapshot` option is removed; the hook starts the supplied actor and stops it when the component is destroyed. This release also marks XState v6 as beta, with no further breaking changes planned for `@public` APIs and possible changes to `@experimental` APIs.
affected
Svelte users who restore actor state or use the removed `snapshot` option are affected.
action
Update code using the `snapshot` option to restore and pass an actor as shown in the release notes.
release_signals
-The `snapshot` option is removed; restore an actor with `restoreActor` from `xstate/persist` and pass the actor to the hook instead.
The Solid hooks `useActorRef`, `useActor`, and `useMachine` now accept an already-created actor, including one restored with `restoreActor`. The `snapshot` option is removed; hooks start the supplied actor on mount and stop it on unmount. XState v6 is in beta, with no further breaking changes planned for `@public` APIs, while `@experimental` APIs may still change.
affected
Solid users of `useActorRef`, `useActor`, or `useMachine` who rely on the removed `snapshot` option are affected, as are users adopting restored actors.
action
Update code that uses the `snapshot` option to pass an actor restored with `restoreActor` instead.
release_signals
-The `snapshot` option is removed from the hooks; restore an actor with `restoreActor` from `xstate/persist` and pass the actor to a hook instead.
XState v6 beta moves persisted actor restoration from `createActor` to `restoreActor` in the `xstate/persist` entry point, and adds snapshot and event validation during restoration. It also makes leftover v5 configuration and unsupported actor options throw, changes macrosteps to be unbounded by default, and improves diagnostics and TypeScript actor-ref types.
affected
Users upgrading to XState v6, especially those restoring persisted actors or carrying v5 configuration and lifecycle event patterns, must update affected APIs and configuration.
action
Review the migration changes before upgrading; use `restoreActor` for persisted snapshots and update v5 configuration or lifecycle event patterns that now throw.
release_signals
-`createActor` no longer restores persisted snapshots; passing `snapshot` throws. Use `restoreActor` instead.
@xstate/vue@6.0.0-alpha.5lowprereleaseNov 2, 2026
@xstate/vue@6.0.0-alpha.5
This prerelease adds stability tags to public exports. Exports are now marked `@public` or `@experimental`.
affected
Users and maintainers relying on the package’s public exports may now see explicit stability labels.
Async logic now preserves `null` as its output when it resolves with `null`, rather than reporting `undefined`. Likewise, rejecting with `null` reports `null` as the error.
affected
Users of async logic that resolves or rejects with `null` will now receive `null` in snapshots and corresponding parent events.
Events sent by a child actor to a parent created with `createEffectActor` now preserve their send order, including bursts emitted from promise continuations. The release also documents an option for durable hosts with a single FIFO mailbox to route all root events through their adapter.
affected
This affects users of `createEffectActor` who rely on child-to-parent event ordering and durable hosts that use a single FIFO mailbox.
action
For durable hosts with a single FIFO mailbox, consider setting `captureRootEvents: false` as shown in the release notes.
release_signals
+Added the `captureRootEvents` option for durable hosts; setting it to `false` routes all root events through the adapter.
-FSM transition functions must return an object or `undefined`, rather than a string.
+Added eventless `always` transitions to `xstate/fsm`, evaluated during initialization and after handled events until none are enabled.
+Callback, event observable, listener, subscription, and `createEffectEventStreamLogic` actors now process events sent to a parent in their own transitions; inspection and subscribers report the source transition.
migration_steps2 steps
01Run the `@xstate/codemod` `string-targets` transform for inline FSM configurations.
02Manually review separately stored FSM configurations and transition functions that return strings.
Serialized field names changed: for example, `$actor` is now `@actor`, `$error` is now `@error`, and private counters such as `_nextTimerId` and `_nextActorIds` are now `nextTimerId` and `nextActorIds`. Consumers that validate or process serialized snapshots and descriptors must account for the new names. Restore functions remain compatible with snapshots using the old names.
-`snapshot.toJSON()` no longer includes the private `_nextTimerId` and `_nextActorIds` counters.
+Export `sendAndAwait` from the main `@xstate/effect` entrypoint; the test entrypoint continues to re-export it for compatibility.
+Preserve registered Effect action keys in transition descriptors so consumers can identify enqueued actions.
migration_steps1 steps
01Update schemas that validate persisted snapshots (for example, schemas using `machineVersions`) to use the new serialized field names.
-`snapshot.toJSON()` no longer includes the private `_nextTimerId` and `_nextActorIds` counters.
migration_steps1 steps
01Update schemas that validate persisted snapshots (for example, schemas using `machineVersions`) to recognize the new field names. Existing snapshots with the old names remain readable by `restoreActor`, `restoreMachineSnapshot`, and `systemTransition`.
Serialized output renames fields such as `$actor`, `$error`, `$stateNode`, `$systemMapper`, `_nextTimerId`, and `_nextActorIds` to names without `$` or `_` prefixes. Consumers and validators of newly written snapshots must use the new names; older beta.1 snapshots remain restorable.
-`snapshot.toJSON()` no longer includes the private `_nextTimerId` and `_nextActorIds` counters.
+Add `durable.checkpoint(snapshot)`, which captures the persisted snapshot, next transition index, and queued root-addressed events for `restore()`.
+Allow `restore()` to accept the new durable checkpoint format while continuing to accept a bare persisted snapshot.
migration_steps1 steps
01Update schemas that validate persisted snapshots, including schemas using `machineVersions`, to use the new serialized field names.
Added report transforms for suffixed lifecycle events, unsupported action/transition shapes, second `createMachine` arguments, and v5 inspection event type strings.
+Added `lower-actions` to rewrite supported v5 action and guard patterns into v6 functions, and to convert object-literal machine implementations and `fromPromise(fn)`.
+Expanded `types-to-schemas` to convert per-key `types` declarations and derive event schemas from same-file type aliases.
+Added `baseline` and `verify` commands to record v5 behavior traces and replay them against v6, with input support and simulated time/random values.
migration_steps1 steps
01Use `baseline` to record a v5 behavior trace, run `migrate --json`, address reported `manualSites`, then use `verify` to compare the migrated module against the baseline.
`useActorRef`, `useActor`, and `useMachine` accept an existing actor; hooks start it on mount and stop it on unmount.
migration_steps1 steps
01Replace use of the removed `snapshot` option by restoring the actor with `restoreActor` from `xstate/persist` and passing it to the hook. Create the actor once per component instance.
-`machine.restoreSnapshot()` is removed, and `machine.snapshotSchema` and `machine.eventSchema` are replaced by functions.
-Leftover v5 machine configuration, implementations passed as a second argument to `createMachine`, and unsupported `createActor` options now throw in every build.
-v5 suffixed lifecycle event types in `on` transitions now throw; use the category event type and select the child with `matches`.
-Macrosteps are unbounded by default; configure `options.maxIterations` to make a runaway macrostep throw `InfiniteTransitionError`.
+Adds `restoreActor(logic, snapshot, options?)` via `xstate/persist` for restoring persisted actors, including invoked and spawned children.
+Adds `snapshotSchema(machine)` and `eventSchema(machine)` functions for validating machine snapshots and events.
+Production errors and diagnostics now use short codes with links to the error reference.
migration_steps5 steps
01Replace `createActor(machine, { snapshot: persisted })` with `restoreActor(machine, persisted)` imported from `xstate/persist`; pass the system through the third argument when restoring into a system.
02Replace `machine.snapshotSchema` and `machine.eventSchema` validation with `snapshotSchema(machine)` from `xstate/persist` and `eventSchema(machine)` from `xstate`.
03Declare implementations in `setup({ ... })` or pass them through `machine.provide({ ... })` instead of passing them to `createMachine`.
04Replace removed actor options with their stated replacements; for `systemId`, use `registryKey` and look up the actor with `system.get(registryKey)`.
05Replace v5 suffixed lifecycle event transitions with the category event type and use `matches` to select the child.