Troubleshooting

See Error Codes for the full return-code reference.

Message Too Large / Truncated

Messages pass through several buffer layers. A message must fit every layer to be delivered intact:

Layer	Env var	Posix default
Defragmentation	NROS_ZENOH_FRAG_MAX_SIZE	65536
Batch size	NROS_ZENOH_BATCH_UNICAST_SIZE	65536
Shim buffer	NROS_SUBSCRIBER_BUFFER_SIZE	1024

For large messages, increase the transport limits before building:

NROS_ZENOH_FRAG_MAX_SIZE=131072 cmake --build build

After changing any buffer variable, clean the build cache:

cargo clean -p zpico-sys
rm CMakeCache.txt

zenoh Version Mismatch

zenoh-pico and zenohd must be the same version. Symptoms: z_publisher_put failed: -100 (_Z_ERR_TRANSPORT_TX_FAILED) followed by -73 (_Z_ERR_SESSION_CLOSED).

The router is the one ROS ships: ros2 run rmw_zenoh_cpp rmw_zenohd. nano-ros vendors none (RFC-0075), and the old build-zenohd recipe was retired with the vendored copy.

Build Issues

• Submodule not found — init that ONE submodule, scoped: git submodule update --init packages/rmw/zenoh/zpico-sys/zenoh-pico. Never --recursive on nano-ros — the transitive closure is large and mostly irrelevant to any one task. nros setup <board> --rmw zenoh provisions it for you, shallow, and is the preferred route.
• CMake cache stale — delete CMakeCache.txt and rebuild. For Cargo-based builds, run cargo clean -p zpico-sys then rebuild.
• NROS_PUBLISHER_SIZE undefined — the build did not run the nros-sizes-build probe. Re-run cargo build -p nros-cpp and verify nros_cpp_config_generated.h is regenerated.

Move and Lifetime

rclcpp::Publisher<M>, rclcpp::Subscription<M>, etc. are non-copyable but movable. The Rust-side handle is relocated through a dedicated FFI call (nros_cpp_*_relocate) — moves are O(1) memcpy + an FFI hop.

rclcpp::Publisher<MyMsg> pub;
node.create_publisher(pub, "/topic");
 
auto pub2 = std::move(pub);   // OK — pub2 owns the handle now
// pub.publish(...) is now invalid (use is_valid() to check)

Storing a publisher inside a container that re-allocates (e.g., std::vector without reserve()) causes implicit moves; that is fine. Holding raw pointers to a publisher across a move is not — re-locate via the FFI re-binds the storage but external pointers stay stale.

Callback ABI in Mixed C++/C

Callbacks passed to the rclcpp::Subscription, rclcpp::Timer, and rclcpp::Service constructors are void(*)(...) C function pointers, not std::function. Lambdas without captures decay implicitly; a capturing lambda needs to be split into a context struct + free function:

struct Ctx { int count; };
static void on_tick(void* ctx_ptr) {
    auto* c = static_cast<Ctx*>(ctx_ptr);
    c->count++;
}
 
Ctx ctx{};
rclcpp::Timer t;
node.create_wall_timer(t, 1000, on_tick, &ctx);

std::function overloads are available under NROS_CPP_STD.

FFI Crash on Subscription Callback

The C++ subscription invokes the user callback on the executor thread. If you use a std::function and the function holds a heap-allocated capture, the allocator must be safe to call from that thread. On no_std / RTOS targets, prefer the freestanding C-pointer form to keep the callback path allocator-free.

Common Result Codes

rclcpp::ErrorCode	Meaning
NotInitialized	rclcpp::init_in() was never called or returned an error
InvalidArgument	Null or empty topic/service name
Timeout	Service / action wait deadline elapsed
Full	Static pool exhausted (raise NROS_*_BUFFER_SIZE)

See Error Codes for the complete table.