Behaviors.failed marks an actor as failed after an exception. The actor stops processing mailbox messages while supervision either terminates it or prepares a replacement incarnation. section 5.3.2 section 5.3.3
Failure followed by termination
An actor processes message X and raises an exception. The supervisor selects Behaviors.failed, so no further mailbox messages are processed. The actor then receives PostStop, allowing cleanup of open connections, files, or other expiring resources, before its mailbox, supervisor, and actor are removed. section 5.3.2
The failed state participates in two supervision paths:
- Stop: transition from Behaviors.failed to Behavior.stopped, process PostStop, and permanently remove the actor. section 5.3.2
- Restart: set Behaviors.failed, deliver PreRestart, stop the faulty incarnation, and create a new actor with the same ActorRef. section 5.3.3
- Restart preserves the communication facade but loses ordinary actor state; persistent actors are required for state retention in harder failure scenarios. section 5.3.3
- Use restartWithBackoff when an external service may remain unavailable, increasing retry delays between a configured minimum and maximum. section 5.3.3
Trace the default supervision path from a failed message through Behaviors.failed, PostStop, and final actor termination. section 5.3.2
Compare the restart lifecycle: failure, PreRestart, removal of the old incarnation, and creation of its replacement. section 5.3.3
