NAME
LibTmux::X - Typed failures with readable diagnostics
DESCRIPTION
Errors stringify with class, path, and message. "Creation" retains its original acquisition exception separately through cause. details returns diagnostic fields. Acquisition failures never represent an empty selection.
METHODS
new
new(%details) constructs an exception object without throwing or I/O.
throw
throw(%details) throws one exception object of the receiving class.
message
Return the human-readable failure description.
path
Return the criterion or argument path, or undef when inapplicable.
entity
Return the entity kind, or undef when inapplicable.
expected
Return the expected operand description, or undef.
received
Return the received operand description, or undef.
matched_ids
Return a fresh arrayref of observed matching IDs, including duplicate occurrences.
count
Return the observed cardinality lower bound where applicable.
result
Return a completed or bounded partial LibTmux::CommandResult, or undef before process dispatch.
dispatched
Return whether the request was submitted where known; undef means no dispatch evidence was recorded. This never proves rollback.
details
Return a fresh shallow hashref of diagnostic fields. Causes and entity handles retain their identity.
created
Creation failures expose a minimal generation-scoped entity receipt, or undef. Only "Creation" in LibTmux::X provides this method.
cause
Return the original acquisition exception for "Creation" in LibTmux::X.
CARDINALITY AND DATA FAILURES
NoMatch
No occurrence matched one().
MultipleMatches
At least two occurrences matched. matched_ids preserves occurrence diagnostics.
InvalidFilter
Invalid criteria data; path, expected, and received describe the boundary.
InvalidSelection
Undefined, hole, wrong-kind, or incompatible-generation membership.
InvalidArgument
Invalid operation or transport argument before dispatch.
Unloaded
A required field or relation is not available in captured data.
UnsupportedValue
A local value has no supported portable wire representation.
Unsupported
A daemon or execution capability is unavailable.
AcquisitionRace
Observed generations or topology changed during capture.
QueryMismatch
Native candidates disagree with captured local matches, or an expert native query returned an uncaptured ID. details->{verification} contains the detached "VERIFICATION REPORT" in LibTmux::Server. The cause may be concurrent change, a translation defect or backend semantics; the comparison does not identify it. "query_panes" in LibTmux::Server throws this for require or expert queries, while auto reports fallback through its optional observer.
StaleReference
A captured generation or contextual target no longer identifies the same resource.
Spawn
The executable could not start; dispatch is distinguished from command failure.
NoServer
The selected server cannot be reached.
Command
tmux reported nonzero status; result retains stdout/stderr/status.
Timeout
Execution exceeded its deadline; effects may already have occurred.
Cancelled
Execution was cancelled; cancellation does not roll back effects.
OutputLimit
Retained process output exceeded the configured bound.
Transport
Process supervision or result framing failed.
Codec
A tmux record or field could not be decoded.
NoSuchTarget
The selected stable target no longer exists. Native result diagnostics are retained. This differs from a stale generation and from an arbitrary command failure; acquire a new snapshot before choosing recovery.
Creation
A creation command succeeded but subsequent receipt decoding or capture failed. created returns a minimal generation-scoped entity handle when the command's receipt was decoded; other fields remain unloaded. cause preserves the original acquisition failure. dispatched is true. The returned handle permits explicit, generation-checked cleanup; absent receipts leave effects uncertain. See "new_session" in LibTmux::Server.
DIAGNOSTICS
message, path, entity, expected, received, matched_ids, count, result, dispatched, and details expose applicable fields. See "one" in LibTmux::Selection, "new" in LibTmux::Filter, and LibTmux::Server for failure boundaries.