Implementation:Ray project Ray RayActorException

Knowledge Sources	Ray
Domains	Distributed_Computing, Java_API
Last Updated	2026-02-13 16:00 GMT

Overview

Exception class indicating that a Ray actor died unexpectedly before finishing a task, provided by the Ray Java API.

Description

RayActorException extends RayException and is thrown when an actor dies unexpectedly before completing a task. This can occur either because the actor process crashes while executing a task, or because a task is submitted to a dead actor. If the actor died because of an exception thrown in its creation task, RayActorException contains that exception as the cause. Multiple constructors capture the ActorId, worker PID, IP address, and optional cause exception, formatting detailed diagnostic messages.

Usage

This exception is thrown by the Ray runtime and should be caught in application code to detect and respond to actor death in Ray's actor-based programming model. It is critical for distributed error handling and failure recovery.

Code Reference

Source Location

• Repository: Ray
• File: java/api/src/main/java/io/ray/api/exception/RayActorException.java

Signature

public class RayActorException extends RayException {
    public ActorId actorId;
    public RayActorException();
    public RayActorException(ActorId actorId);
    public RayActorException(int pid, String ipAddress, ActorId actorId, Throwable cause);
    public RayActorException(int pid, String ipAddress, Throwable cause);
}

Import

import io.ray.api.exception.RayActorException;

I/O Contract

Inputs

Name	Type	Required	Description
actorId	ActorId	No	Identifier of the actor that died
pid	int	No	Process ID of the dead actor worker
ipAddress	String	No	IP address where the actor was running
cause	Throwable	No	The underlying exception that caused the actor death

Outputs

Name	Type	Description
exception	RayActorException	Exception instance with diagnostic message and actor ID

Usage Examples

ActorHandle<MyActor> actor = Ray.actor(MyActor::new).remote();
ObjectRef<String> result = actor.task(MyActor::process).remote();

try {
    String value = result.get();
} catch (RayActorException e) {
    System.err.println("Actor " + e.actorId + " died: " + e.getMessage());
    // Handle actor failure - e.g., recreate the actor
}

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment