Cineyma

Errors

Error types returned by actor operations.

MailboxError

Error type returned when sending messages to actors fails.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Variants

MailboxClosed

The actor has stopped and its mailbox is closed. No more messages can be delivered.

Common Causes

  • -Actor called ctx.stop()
  • -Actor panicked during message handling
  • -Parent actor stopped (for child actors)
  • -System shutdown was called
Timeout

The operation exceeded the specified timeout duration.

Common Causes

  • -Actor is overloaded and processing slowly
  • -Actor is blocked on I/O
  • -Deadlock in message handling
MailboxFull

The actor's mailbox is at capacity. Only returned by try_send methods.

Common Causes

  • -Actor processing messages slower than receiving
  • -Mailbox capacity too small for workload
  • -Actor blocked on slow operation

Error Handling Patterns

Propagate with ?

1
2
3
4
5
6
7
8
9
10
11
12

Match and Handle

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Graceful Degradation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Circuit Breaker

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

Best Practices

Always handle MailboxClosed

Actors can stop at any time. Check is_alive() or handle the error to avoid sending to dead actors.

Use timeouts for external calls

When calling actors that perform I/O, use send_timeout to prevent indefinite blocking.

Use try_send for non-critical messages

For notifications, metrics, or other non-essential messages, use try_send to avoid back-pressure.

Size mailboxes appropriately

MailboxFull indicates the producer is faster than the consumer. Increase capacity or add more consumers.

Log and monitor errors

Track mailbox errors to identify overloaded actors or system issues.

Converting Errors

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

Related

Address API

Methods that return MailboxError

Supervision

Handle actor failures with supervision