errors

Classes

RSessionError

Bases: RuntimeError

Error raised when a worker call fails.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error message (often derived from R error messages).	required
remote_traceback	str or None	Best-effort traceback text from the worker process. For R errors this may be an R traceback string; for Python errors inside the worker it may be a Python traceback.	None

Notes

This exception type is designed to preserve the remote failure context while keeping the main process free of rpy2/R state.

Functions

__str__()

Return message plus the remote traceback (if available).

RWorkerCrashedError

Bases: RuntimeError

Raised when the R worker process crashes during an operation.

Parameters:

Name	Type	Description	Default
message	str	Human-readable description of the failure.	required
recovered	bool	Indicates whether a fresh worker session was successfully started. True – The crash occurred, but automatic recovery succeeded. The failed operation did not complete, but the worker is now in a clean state. Callers may safely retry. False – The crash occurred and automatic recovery failed. A usable worker session is not available. Callers should treat this as a hard failure and abort or escalate.	required
cause	BaseException	The original exception that triggered the crash. Stored as __cause__ for chained exception inspection.	None

Usage

In user code or automated pipelines, you can distinguish between a recoverable and unrecoverable crash:

try:
    brms.brm(...)
except RWorkerCrashedError as err:
    if err.recovered:
        # Crash occurred, but a fresh worker is ready.
        # Safe to retry the operation once.
        brms.brm(...)
    else:
        # Worker could not be restarted.
        # Treat this as a hard failure.
        raise

Notes

All crashes automatically produce a new exception that wraps the original failure using Python's exception chaining (raise ... from cause). Inspect err.__cause__ for the underlying system error.