fujilib.errors¶

Structured context attached to every :class:FujiError.

Fields are best-effort — missing data is None rather than raising.

protocol and channel are typed as str so they accept the library's ProtocolKind and ChannelId string enums as well as plain strings. register_address is the 0-based on-the-wire address, not the 30001/40001-based register number.

extra accepts any Mapping and is always frozen into a read-only :class:types.MappingProxyType at construction so the shared empty sentinel can never be mutated through error.context.extra[k] = v.

merged(**updates)

78
79
80
81
82
83
84
85
86
87
88
89
90
91

def merged(self, **updates: Any) -> Self:
    """Return a new context with ``updates`` overlaid. Unknown keys go to ``extra``."""
    known: dict[str, Any] = {}
    extra_updates: dict[str, Any] = {}
    for key, value in updates.items():
        if key in _CONTEXT_KNOWN_FIELDS:
            known[key] = value
        else:
            extra_updates[key] = value

    new_extra: Mapping[str, Any] = (
        MappingProxyType({**self.extra, **extra_updates}) if extra_updates else self.extra
    )
    return replace(self, **known, extra=new_extra)

Bases: FujiError

What the analyzer is doing forbids the write or command now; nothing was written.

Raised after reading the analyzer's status and before any write (design §6.1): a calibration is running, the front panel shows a menu, or the analyzer reports an error that makes a calibration meaningless. Retryable once the analyzer is back on the measurement screen.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiError

The operation is not available on this analyzer, model or option.

Raised before any I/O once a capability is known to be UNSUPPORTED (design §6.6). Not retryable until reprobe().

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiError

Configuration-level error: bad arguments or conflicting settings.

Not retryable: the call itself has to change. A ValueError escaping anymodbus is a fujilib bug and also surfaces here (design §4.4).

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiConfigurationError

An operation above SafetyTier.READ_ONLY was attempted without confirm=True.

Raised before any I/O (design §6.1). Retry only by passing confirm=True deliberately.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiTransportError

The port could not be opened, or the connection was lost.

Retryable only after the device is reopened.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiProtocolError

A register value was received intact but does not decode.

Examples: a BCD digit above 9, an enum value the manual does not define. Not retryable. Distinct from :class:FujiConfigurationError (design §4.4).

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: Exception

Base class for every :mod:fujilib exception.

Carries a typed :class:ErrorContext. The message is the human-readable summary; the context is the machine-readable detail.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

with_context(**updates)

151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

def with_context(self, **updates: Any) -> Self:
    """Return a copy of this error with its context updated.

    Useful when an inner layer raises and an outer layer wants to enrich
    the context (for instance adding ``port`` or ``elapsed_s``).
    """
    cls = type(self)
    new = cls.__new__(cls)
    new.args = self.args
    try:
        new.__dict__.update(self.__dict__)
    except AttributeError:  # pragma: no cover — no slotted subclass today
        for slot in getattr(cls, "__slots__", ()):
            if hasattr(self, slot):
                object.__setattr__(new, slot, getattr(self, slot))
    new.context = self.context.merged(**updates)
    new.__cause__ = self.__cause__
    new.__context__ = self.__context__
    new.__traceback__ = self.__traceback__
    return new

Bases: FujiCapabilityError

The operation needs firmware the analyzer does not have.

For example, the calibration log needs firmware 2.24 or later. Not retryable.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiProtocolError

Bad CRC, wrong length or malformed framing.

Usually link noise. Reads are retried by the client; writes are not.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiProtocolError

A Modbus exception response or other Modbus-layer failure.

__cause__ preserves the original anymodbus exception.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiModbusError, FujiProtocolUnsupportedError

Modbus exception 02 — the address is outside the analyzer's map.

For a well-formed capability probe this marks the capability UNSUPPORTED (design §6.6). Not retryable.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiModbusError

Modbus exception 03 — illegal data value.

The manual describes it as "too many words requested / outside the map"; the bench unit also returns it for a read that crosses a region end (design §2.2). Not retryable.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiModbusError, FujiProtocolUnsupportedError

Modbus exception 01 — the function code is not implemented.

The bench unit answers FC01 and FC02 with exception 02 instead (design §2.2). Not retryable.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiModbusError, FujiTimeoutError

No reply arrived within the request timeout.

A bad CRC, a wrong station number or an over-long inter-byte gap all produce no reply (design §2.2). Reads are retried by the client and each retry is counted (design §4.5); writes are not.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiError

Protocol-level error: framing, decoding, or an unexpected reply.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiProtocolError

The analyzer does not support this request at all. Not retryable.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiTransportError

The port is still discarding a possible late reply after a cancellation.

New requests are refused until resynchronization completes (design §4.2); retry after it has.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiSinkError, FujiConfigurationError

A sink's optional backing library is not installed.

Also a :class:FujiConfigurationError, because a missing extra is a configuration problem from the caller's point of view. Not retryable until the extra is installed.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiError

Base class for errors raised by sinks.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiSinkError

A batch's shape is incompatible with the sink's locked schema. Not retryable.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiSinkError

The backing store rejected a write.

__cause__ preserves the backend's exception; whether a retry can help depends on it.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiTransportError

A transaction timed out, or a per-call operation deadline expired.

For a deadline, the context carries the operation name and the elapsed time (design §4.6, §6.4). Reads may be retried. A write that timed out raises :class:FujiWriteOutcomeUnknownError instead.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiError

I/O-layer error from the serial transport or the Modbus bus.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiConfigurationError

A request failed validation before any I/O.

Examples: an unknown parameter name, a channel or range that does not exist, a value outside its raw limits. Not retryable.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiProtocolError

The read-back after a write did not match the value written.

The context carries the expected and observed values. Not retryable: the front panel may have changed the setting in between (design §6.3).

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT

Bases: FujiTimeoutError

A write request was sent but its outcome could not be established.

The analyzer may have applied the write even though the reply was lost (design §6.4). Not retryable: read the setting back and decide. The context's extra records the write_state, whether transmission started, and any observed value.

147
148
149

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context if context is not None else _EMPTY_CONTEXT