Error catalogue

Reference · generated · every public error type in the workspace, variant by variant, with the meaning its documentation states

The table is read from the source, so a variant that exists is listed and a variant that is gone disappears. The troubleshooting guide gives remedies for the errors a user meets from the command line.

`ShmError` in `core/core-region`

Defined in core/core-region/src/lib.rs.

Variant	Meaning
`Open`	`shm_open(3)`, `fstat(2)` or a header read failed; the field is the `errno`.
`Truncate`	`ftruncate` failed; the field is the `errno`.
`NoSpace`	Linux could not reserve a new region’s page: `posix_fallocate(3)` failed, with `ENOSPC` on a full `/dev/shm`, `ENOMEM`, or `EINTR` after [`RESERVE_ATTEMPTS`] tries. The object was unlinked and nothing was mapped. Never returned off Linux.
`Map`	`mmap` failed; the field is the `errno`.
`InvalidName`	The name contains a NUL byte.
`RegionTooSmall`	The object is smaller than a region, [`REGION_SIZE`] bytes.
`LayoutMismatch`	The header is not a region’s: the magic is not `PMRG` (not a region, or not yet published), or the layout version is not [`LAYOUT_VERSION`]. Nothing was mapped.

`NumaError` in `core/core-region`

Defined in core/core-region/src/numa.rs.

Variant	Meaning
`HugePageAlloc`	Making a memfd ([`allocate_hugepage_memfd`]) or duplicating a descriptor ([`dup_fd`]) failed; the string says what and why.
`NumaPin`	Pinning a thread or binding memory to a NUMA node failed: `sched_setaffinity(2)` or `mbind(2)` refused, the node is past the 64 a binding can name, or a CPU number is past the `CPU_SETSIZE` (1024) a `cpu_set_t` can name.
`UnsupportedPageSize`	Caller requested a page size the kernel doesn’t expose. Check `/sys/kernel/mm/hugepages` to see what’s available.
`LibnumaMissing`	The operation is Linux-only: binding memory, detecting a node, pinning a thread and hugepage memfds return this elsewhere. Nothing links libnuma; on Linux these are the kernel’s system calls.
`Io`	Underlying I/O failure (typically while creating or sizing the SHM file).

`Error` in `core/core-region`

Defined in core/core-region/src/shm.rs.

Variant	Meaning
`Open`	`shm_open(3)` or the `fstat(2)` after it failed; the field is its `errno` (`EEXIST` from an exclusive creation whose name already holds an object, `ENOENT` from an open of a name that holds none, `EACCES` from a runtime that refuses POSIX shared memory, `EBADF` from a descriptor that is not open).
`Truncate`	`ftruncate(2)` could not size the new object; the field is its `errno` (`EFBIG`, `ENOSPC`).
`NoSpace`	Linux could not reserve a new object’s pages: `posix_fallocate(3)` failed, with `ENOSPC` on a full `/dev/shm`, `ENOMEM`, or `EINTR` after [`RESERVE_ATTEMPTS`] tries. Never returned off Linux.
`Map`	`mmap(2)` failed; the field is its `errno`.
`InvalidName`	The name holds a NUL byte, which no C string can carry.
`TooSmall`	The object is shorter than the caller needs: `have` bytes where `need` are needed. An object at size zero is one a creator has made and not yet sized.

`RingError` in `core/core-ring`

Defined in core/core-ring/src/lib.rs.

Variant	Meaning
`Open`	`shm_open(3)`, `fstat(2)` or a header read failed; the field is the `errno`.
`Truncate`	`ftruncate` failed; the field is the `errno`.
`NoSpace`	Linux could not reserve a new ring’s pages: `posix_fallocate(3)` failed, with `ENOSPC` on a full `/dev/shm`, `ENOMEM`, or `EINTR` after [`RESERVE_ATTEMPTS`] tries. Nothing was mapped: a creator by name unlinked its object, and [`PulseRing::from_fd`] left the descriptor open and unformatted. Never returned off Linux.
`Map`	`mmap` failed; the field is the `errno`.
`Unlink`	`shm_unlink` failed; the field is the `errno`.
`InvalidName`	The ring name contains a NUL byte, or is not a valid hub name.
`InvalidCapacity`	Zero slots; or, from a constructor that sizes or formats a region, a ring whose size, `HEADER_SIZE + capacity × slot size`, does not fit a `usize` and a file offset. Nothing was created, opened or mapped.
`BatchTooLarge`	A batch publish was given more pulses than the ring has slots; nothing was written. Publish at most `capacity` pulses per batch.
`Stalled`	A blocking publish waited its whole timeout and the slowest reader never freed the room it needed: it stopped, died, or there is none. Nothing was published, so the call can be retried.
`NoReaderTable`	[`PulseRing::register_reader`] on a ring made without a reader table.
`ReadersFull`	Every line of the ring’s reader table is taken.
`InvalidReaders`	A reader table of `max_readers` lines: it needs from 1 to [`MAX_READERS`]. Nothing was created.
`NameTooLong`	A derived shared-memory name exceeds the platform limit.
`RegionTooSmall`	The object is smaller than the ring the caller asked to map, which would fault past its end.
`LayoutMismatch`	The header does not describe the ring the caller maps: the magic is not `PMSR` (not a ring, or not yet formatted), or the layout version, capacity or slot size differs.
`CrcMismatch`	[`PulseRing::read_slot_verify_crc`] found a slot whose CRC32C trailer does not match its data.

`EnvelopeStoreError` in `core/core-store`

Defined in core/core-store/src/lib.rs.

Variant	Meaning
`Open`	`shm_open(3)`, `fstat(2)` or a header read failed; the field is the `errno`.
`Truncate`	`ftruncate` failed; the field is the `errno`.
`NoSpace`	Linux could not reserve a new store’s pages: `posix_fallocate(3)` failed, with `ENOSPC` on a full `/dev/shm`, `ENOMEM`, or `EINTR` after [`RESERVE_ATTEMPTS`] tries. The object was unlinked and nothing was mapped. Never returned off Linux.
`Map`	`mmap` failed; the field is the `errno`.
`Unlink`	`shm_unlink` failed; the field is the `errno`.
`InvalidName`	The name contains a NUL byte.
`InvalidCapacity`	Zero slots, more than the header’s 32-bit capacity field can record, or so many that `64 + capacity × slot size` does not fit a `usize` and a file offset. Nothing was opened, created or mapped.
`RegionTooSmall`	The object is smaller than the store the caller asked to map, or, for [`EnvelopeStore::open_existing`], than a header or the store its header describes.
`LayoutMismatch`	The header does not describe the layout this build uses.
`SlotBusy`	Each of the [`CLAIM_ATTEMPTS`] cursors tried found its slot held or taken by a newer lap, or named a lap too large to mark (a write cursor corrupted in shared memory). Nothing was written; readers skip every cursor given up.
`InvalidIndex`	An index of `buckets` buckets for a store of `capacity` slots: the count must be a power of two no larger than the capacity rounded up to one. Nothing was created.
`EnvelopeTooLarge`	The envelope’s canonical encoding exceeds [`MAX_ENTRY_SIZE`] bytes.

`TransportError` in `core/core-transport`

Defined in core/core-transport/src/lib.rs.

Variant	Meaning
`Io`	Underlying I/O failure (socket, file, kernel).
`BufferTooSmall`	The caller’s envelope buffer is smaller than the incoming envelope.
`Decode`	A frame failed the wire format’s validation (magic, version, length, CRC, or the backend’s own checks).
`EnvelopeTooLarge`	The envelope exceeds the transport’s `max_envelope()`.
`Send`	A send failed for a reason `Io` does not fit, such as the backend’s flow control stalling (the UDP transport’s backpressure window, which its opt-in congestion control sizes).
`Recv`	A receive failed for a reason `Io` and `Decode` do not fit.

`FecError` in `core/pulse-wire-udp`

Defined in core/pulse-wire-udp/src/fec.rs.

Variant	Meaning
`TooShort`	Buffer is shorter than [`FEC_HEADER_BYTES`].
`MagicMismatch`	First 4 bytes don’t match [`FEC_MAGIC`].
`Truncated`	Length-prefix says the parity payload is `parity_len` bytes but the buffer doesn’t actually carry that many.
`InvalidWindow`	The header declares a window of zero frames, which could rebuild nothing; refused here, before it reaches the decoder’s arithmetic.

`ReceiverError` in `core/pulse-wire-udp`

Defined in core/pulse-wire-udp/src/receiver.rs.

Variant	Meaning
`Io`	Socket I/O error. `WouldBlock` from a timeout is one of these.
`Decode`	The datagram failed wire-format validation (magic, version, length or CRC).
`BufferTooSmall`	The envelope does not fit the buffer given to [`Receiver::recv_into`]; the frame is consumed.
`InvalidPulseBytes`	A decoded frame’s 128 pulse bytes are not a [`pulse_canon::Pulse`]: a sender bug.

`BatchRecvError` in `core/pulse-wire-udp`

Defined in core/pulse-wire-udp/src/receiver.rs.

Variant	Meaning
`Io`	Reading the first datagram failed, so nothing was read; a timeout (`WouldBlock` or `TimedOut`) means none arrived within the socket’s read timeout.
`BatchTooLarge`	`max_frames` exceeded [`crate::sender::MAX_BATCH_FRAMES`].
`InsufficientBuffers`	`envelopes.len()` is smaller than `max_frames`.

`SealError` in `core/pulse-wire-udp`

Defined in core/pulse-wire-udp/src/sealed.rs.

Variant	Meaning
`Io`	The socket refused a handshake message.
`KeyFile`	The key file could not be opened, created, read or written.
`KeyFileExposed`	The key file can be read or written by its group or by others, or is not a regular file; it is not loaded.
`InvalidKey`	Text that should name a key is not 64 hex digits.
`NotAllowed`	The peer’s key is not on this node’s allowlist.
`HandshakeTimeout`	No response to the handshake arrived within the timeout.
`NoSession`	There is no session to the destination: [`Sealing::connect`] first, or the session was dropped, idle, or spent its counter.
`Crypto`	The Noise library or the system’s entropy source refused.

`SenderError` in `core/pulse-wire-udp`

Defined in core/pulse-wire-udp/src/sender.rs.

Variant	Meaning
`Io`	Underlying socket I/O failure.
`Encode`	The frame failed to encode: [`WireError::EnvelopeTooLarge`] for an envelope over [`Sender::envelope_limit`]. The sender does not fragment.
`NoDestination`	No destination — caller must `connect()` or use [`Sender::send_to`].
`Stalled`	Backpressure held the send past `stall_timeout`: the receiver’s cursor did not come within `target_queue_depth` frames of the next sequence number. The frame was not sent and its sequence number not used, so the call can be retried.
`InvalidQueueDepth`	[`Sender::enable_backpressure`] was given a `target_queue_depth` of zero, which admits no frame; the sender’s backpressure stays as it was.
`Seal`	Sealing is installed and the frame could not be sealed: [`SealError::NoSession`] when no session to the destination is in use ([`Sealing::connect`] first). Found before the send waits on backpressure; the frame was not sent and its sequence number not used.

`BatchSendError` in `core/pulse-wire-udp`

Defined in core/pulse-wire-udp/src/sender.rs.

Variant	Meaning
`FrameError`	The frame at `index` failed: its encode, a backpressure stall past `stall_timeout`, or its send (on Linux, a `sendmmsg(2)` failure after earlier frames went out). The frames before `index` were sent; the rest were not.
`BatchTooLarge`	The batch is longer than [`MAX_BATCH_FRAMES`]. Nothing was sent.
`PartialSend`	`sendmmsg(2)` took fewer frames than it was given (Linux): the first `sent` were sent, the rest not. The kernel drops the error of any frame after a call’s first, so resending the tail is how to learn it.
`Io`	`sendmmsg(2)` returned -1 for the batch’s first frame (Linux); carries the underlying `errno`. Nothing was sent.

`WireError` in `core/pulse-wire-udp`

Defined in core/pulse-wire-udp/src/wire.rs.

Variant	Meaning
`BufferTooSmall`	The buffer is shorter than a frame with no envelope, [`HEADER_BYTES`] + [`TRAILER_BYTES`].
`InvalidEnvelopeLength`	The frame declares an envelope longer than [`MAX_ENVELOPE`] or than the buffer holds.
`BadMagic`	Magic mismatch — datagram is not a pulse-wire-udp frame.
`UnsupportedVersion`	Version mismatch.
`CrcMismatch`	CRC32C mismatch — wire-level bit-flip or mid-stream truncation; receivers count this toward loss metrics.
`EnvelopeTooLarge`	The envelope is too large for one datagram, or, from a sender with FEC on, for its window’s parity to fit one; with fragmentation on, too large for a run of fragments. Refused before anything is sent, so the caller can chunk.
`InvalidFragment`	A fragment that disagrees with itself: an index or count out of range, a total length over [`crate::fragment::MAX_MESSAGE`], or a sequence number that is not its run’s first plus its index ([`crate::fragment::decode_fragment`]).
`EnvelopeCodec`	A decoded [`Frame`]’s envelope bytes are not a canonical [`PulseEnvelope`]. Returned only by [`decode_with_envelope`].
`EnvelopeIdMismatch`	The envelope decoded, but its content id is not the id of its type, name and payload: the frame passed its CRC, so the id is stale or forged. Returned only by [`decode_with_envelope`].

`NegotiationError` in `pulse/mesh-capability`

Defined in pulse/mesh-capability/src/lib.rs.

Variant	Meaning
`TooShort`	Buffer is shorter than [`HELLO_BYTES`].
`MagicMismatch`	First 4 bytes don’t match [`HELLO_MAGIC`].
`UnsupportedVersion`	Remote’s protocol version is newer than [`MAX_VERSION`].

`ContextRegistryError` in `pulse/mesh-context`

Defined in pulse/mesh-context/src/lib.rs.

Variant	Meaning
`IdConflict`	Two different entries share a `context_id`.
`Toml`	TOML parse failure on [`ContextRegistry::from_toml`].
`Json`	JSON failure in [`ContextRegistry::from_json`] or [`ContextRegistry::to_json`].

`LexRegistryError` in `pulse/mesh-lex`

Defined in pulse/mesh-lex/src/registry.rs.

Variant	Meaning
`Duplicate`	Insert refused: an entry with the same `(type_id, kind)` is already registered.
`NameConflict`	[`LexRegistry::validate`] found two entries with one name.

`EnvelopeCodecError` in `pulse/pulse-canon`

Defined in pulse/pulse-canon/src/envelope.rs.

Variant	Meaning
`BufferTooSmall`	Buffer shorter than the fixed-header + minimum tail.
`Truncated`	A length-prefixed field declared more bytes than `buf` contained.
`InvalidTypeNameTag`	`type_name` presence tag was neither 0 (None) nor 1 (Some).
`InvalidTypeName`	`type_name` bytes were present but not valid UTF-8.
`NestedCountExceedsBuffer`	A nested payload declares more children than the remaining bytes can hold, at [`MIN_CANONICAL_ENVELOPE`] bytes each.
`NestingTooDeep`	Nesting deeper than [`MAX_NESTING_DEPTH`], which the format itself does not limit.
`InvalidPayloadVariantTag`	Payload variant tag was neither [`PAYLOAD_VARIANT_RAW`] nor [`PAYLOAD_VARIANT_NESTED`].
`NestedDecode`	A nested child failed to decode.
`UnknownFlags`	The flags word sets a bit no [`PulseEnvelopeFlags`] flag defines.
`TrailingBytes`	[`PulseEnvelope::from_canonical_bytes`] was given bytes after the envelope.

`SmokeError` in `tools/pulse-cli`

Defined in tools/pulse-cli/src/ops/bench.rs.

Variant	Meaning
`ReceiverSetup`	The receiving socket could not be bound or configured.
`Sender`	Sender-side failure (bind, connect, or per-pulse send).
`Recv`	Receiving or decoding a pulse failed.
`SendThreadPanic`	The sending thread panicked.

`RoundtripError` in `tools/pulse-cli`

Defined in tools/pulse-cli/src/ops/codec.rs.

Variant	Meaning
`DecodeFailed`	The supplied envelope could not be re-decoded from its own canonical form.

`DecodeError` in `tools/pulse-cli`

Defined in tools/pulse-cli/src/ops/codec.rs.

Variant	Meaning
`Hex`	Input was not valid hex.
`Codec`	Decoded bytes did not parse as a canonical envelope.

`SendError` in `tools/pulse-cli`

Defined in tools/pulse-cli/src/ops/udp.rs.

Variant	Meaning
`Bind`	Underlying socket bind failed.
`Send`	Underlying sender failed.

`RecvError` in `tools/pulse-cli`

Defined in tools/pulse-cli/src/ops/udp.rs.

Variant	Meaning
`Bind`	The socket could not be bound or configured.
`Recv`	Underlying receiver failed.

Keyboard shortcuts

Pulse Mesh