nros/guide/troubleshooting.rs
1//! # Troubleshooting
2//!
3//! ## Message too large / truncated
4//!
5//! Messages pass through multiple buffer layers. A message must fit every
6//! layer to be delivered intact:
7//!
8//! | Layer | Env var | Posix default |
9//! |-------|---------|---------------|
10//! | Defragmentation | `ZPICO_FRAG_MAX_SIZE` | 65536 |
11//! | Batch size | `ZPICO_BATCH_UNICAST_SIZE` | 65536 |
12//! | Shim buffer | `ZPICO_SUBSCRIBER_BUFFER_SIZE` | 1024 |
13//! | User receive buffer | — (const generic) | 1024 |
14//!
15//! For large messages, increase the transport limits (set before `cargo
16//! build`) and size the per-entity buffer via the builder's `.rx_buffer::<N>()`:
17//!
18//! ```ignore
19//! // 4 KB receive buffer
20//! executor.node_mut(node).subscription("/topic").typed::<MyMsg>()
21//! .rx_buffer::<4096>().build(|msg| { ... })?;
22//! ```
23//!
24//! ## zenoh version mismatch
25//!
26//! zenoh-pico and zenohd must be the same version (1.6.2). Symptoms:
27//! `z_publisher_put failed: -100` (`_Z_ERR_TRANSPORT_TX_FAILED`) followed
28//! by `-73` (`_Z_ERR_SESSION_CLOSED`).
29//!
30//! Build zenohd from the pinned submodule (`just build-zenohd`) or install
31//! the matching version.
32//!
33//! ## Build issues
34//!
35//! - **Submodule not found** — run `git submodule update --init --recursive`
36//! - **CMake cache stale** (changed env vars not taking effect) — run
37//! `cargo clean -p zpico-sys` then rebuild
38//!
39//! ## zenoh-pico error codes
40//!
41//! | Code | Name | Meaning |
42//! |------|------|---------|
43//! | -3 | `_Z_ERR_TRANSPORT_OPEN_FAILED` | Cannot connect to router |
44//! | -73 | `_Z_ERR_SESSION_CLOSED` | Session closed after failure |
45//! | -78 | `_Z_ERR_SYSTEM_OUT_OF_MEMORY` | Allocation failed |
46//! | -100 | `_Z_ERR_TRANSPORT_TX_FAILED` | Transport transmission failed |
47//! | -128 | `_Z_ERR_GENERIC` | Generic error |