# Trigger a Transition

Once you have a FSM you need to trigger a transition to a new state.

This is done with the `StateMachine().applyEvent` method.

```dart
var machine = StateMachine.create((g) => g
          ..initialState<Solid>()
          ..state<Solid>((b) => b
            ..on<OnMelted, Liquid>(
                sideEffect: (e) => watcher.log(onMeltedMessage))
            ..onEnter((s, e) => watcher?.onEnter(s))
            ..onExit((s, e) => watcher?.onExit(s)))
          ..state<Liquid>((b) => b
            ..onEnter((s, e) => watcher?.onEnter(s))
            ..onExit((s, e) => watcher?.onExit(s))
            ..on<OnFroze, Solid>(
                sideEffect: (e) => watcher.log(onFrozenMessage))
            ..on<OnVaporized, Gas>(
                sideEffect: (e) => watcher.log(onVaporizedMessage)))
          ..state<Gas>((b) => b..on<OnCondensed, Liquid>(
              sideEffect: (e) => watcher.log(onCondensedMessage)))
        );
machine.applyEvent(OnFroze());
```

The `applyEvent` method takes an Event and may cause the FSM to transition to a new state.

{% hint style="info" %}
If you have concurrent regions or nested states then a single event may result in multiple transitions.
{% endhint %}

You should be aware that some calls to \`applyEvent\` will not result in a change in State. This can happen due to [Guard Conditions ](/transitions/guard-conditions.md)suppressing the transition.

Calls to `StateMachine.applyEvent` are asynchronous.&#x20;

{% hint style="info" %}
Your state machine will not have finished transitioning when applyEvent returns! Use an onEnter, onExit, sideEffect or stream to get notifications of when the statemachine has entered a new state.
{% endhint %}

Calls to `StateMachine.applyEvent` can be made at any time and from any code.&#x20;

The StateMachine will queue any events and only apply the event once any active or pre existing queued  events have completed.

## Invalid Transitions

If you call applyEvent with an event you must be in a state that has an handler for that event.

```dart
final machine = StateMachine.create((g) => g
    ..initialState<Solid>()
    ..state<Solid>((b) => b
      ..on<OnMelted, Liquid>(sideEffect: (e) async => print('Melted'))
    ..state<Liquid>((b) => b
      ..on<OnFroze, Solid>(sideEffect: (e) async => print('Frozen'))
      ..on<OnVaporized, Gas>(sideEffect: (e) async => print('Vaporized')))
    ..state<Gas>((b) => b
      ..on<OnCondensed, Liquid>(sideEffect: (e) async => print('Condensed'))));

  machine.applyEvent(OnFroze());

```

The above call to 'machine.applyEvent' will fail as the initialState is 'Solid' and the 'Solid' state doesn't have a handler for the 'OnFroze' event.

{% hint style="info" %}
Note: FSM2 supports inherited transition handlers so an event can be processed if an active State OR one of its parents has a handler for the state.
{% endhint %}

If the statemachine is can't handle the event then a 'InvalidTransitionException' is thrown.

The exception is thrown only when in debug mode. If you pass 'production: true' to the statemachine 'create' method then the exception will be suppressed and instead it will be logged. This is done to make the FSM less brittle in production. &#x20;

## Concurrent Regions

If you have [concurrent regions](/states/concurrent-states.md) in you FSM and a concurrent region is active when an event is applied, only one of the active states needs to be able to handle the event. If at least on of the actives states handles the event then an 'InvalidTransitionException' will not be thrown.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fsm2.onepub.dev/transitions/trigger-a-transition.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.