# Troubleshooting
## Schema names are missing
- v4.0.0 does not generate application endpoint/type constants at compile time.
- Register endpoints and data types at startup, seed them from JSON, or wait for discovery sync.
- For runtime JSON seeding, use `SEDSNET_STATIC_SCHEMA_PATH`,
`SEDSNET_STATIC_IPC_SCHEMA_PATH`, or the explicit JSON file/bytes API for your language.
- Use name lookup helpers such as `DataEndpoint::try_named(...)`,
`seds_endpoint_get_info_by_name(...)`, or `endpoint_info_by_name(...)` before logging.
## Schema mismatch between systems
Nodes synchronize runtime schema through discovery when that feature is enabled. Compatible
endpoint/type definitions merge as nodes learn from each other. Direct registration of the same
name or ID with a different shape returns an error.
Symptoms:
- Unknown `DataType` / `DataEndpoint` errors before discovery converges.
- Registration errors for an existing type with a different size or element shape.
- Discovery warnings for conflicting schema definitions.
Fix:
- Prefer stable names and IDs for long-lived schemas.
- Seed shared required entries from JSON on every node when you need them available immediately.
- If two nodes define the same type differently, rename one of them or change the payload shape so
the definition is identical everywhere.
## Size mismatch errors
If you see `TelemetryError::SizeMismatch`:
- Check the schema definition for the message type.
- Ensure static payloads match exact size.
- Ensure dynamic payloads are a multiple of the element width.
## UTF-8 errors for strings
String payloads must be valid UTF-8. Trailing NULs are ignored but invalid byte sequences will fail validation.
## Compression errors
If a receiver was built without the `compression` feature, it cannot decode compressed payloads. Ensure all nodes share
the same feature set or disable compression everywhere.
## Packets not forwarding
Check:
- The router has active sides and the relevant routes are enabled.
- Link-local-only endpoints stay on link-local/software-bus sides.
- Non-local endpoints depend on discovery state for selective remote routing.
- Your TX callback is installed (non-NULL) and returns OK.
## Echo loops
If you see packets bouncing endlessly:
- Ensure your side TX callback does not immediately re-inject back into the same side.
- Confirm dedupe cache sizes are large enough for your traffic patterns.
## Dropped packets or queue evictions
Queues are bounded by one shared `MAX_QUEUE_BUDGET` per router or relay. RX work, TX work,
recent packet IDs, reliable buffers/replay state, discovery topology, and runtime schema registry
memory all draw from that same budget. Recent packet ID caches reserve their final storage up
front, so a large
`MAX_RECENT_RX_IDS` leaves less budget for active packet queues. If traffic is bursty:
- Increase `MAX_QUEUE_BUDGET` or `QUEUE_GROW_STEP`.
- Process queues more frequently.
- Lower `MAX_RECENT_RX_IDS` if dedupe history is reserving too much of the shared budget.
- If you see topology eviction warnings, either increase `MAX_QUEUE_BUDGET`, reduce discovery churn,
or process queues more often so topology/control traffic does not compete with backed-up data.
## Compact side frames are dropped after link loss
A compact frame can arrive before its full side-template frame on a lossy or reconnecting datagram
link. Router packed sides treat an unknown template as a nonfatal dropped frame. The router sender
refreshes each active template with a full frame after eight compact uses, so delivery should resume
without recreating the router or side. Relay packed sides do not currently have this automatic
refresh behavior. If router delivery does not recover:
- Verify both peers use compatible side-transport profiles and template limits.
- Check that full `SDT` frames are allowed by the underlying transport and frame-size configuration.
- Inspect per-side runtime stats for full/compact counts, active TX/RX templates, and evictions.
- Use the `canonical` profile while diagnosing a link that persistently drops template refreshes.
## Embedded build fails with missing symbols
Bare-metal targets must provide `telemetryMalloc`, `telemetryFree`, and `seds_error_msg`.
## macOS C system test linker target warnings
If C system tests print warnings like "object file ... built for newer 'macOS' version than being linked":
- Ensure Rust staticlib and CMake link use the same deployment target.
- In this repo, `c-system-test/CMakeLists.txt` pins `CMAKE_OSX_DEPLOYMENT_TARGET` and forwards it into Rust builds.
- If you maintain a custom CMake integration, set `CMAKE_OSX_DEPLOYMENT_TARGET` explicitly and keep it consistent.
## Python import fails
- Ensure you built the extension with `./build.py python` or `maturin develop`; see
[build.py](https://github.com/Rylan-Meilutis/sedsnet/blob/main/build.py).
- Verify you are using the same Python interpreter/venv used for the build.
- If runtime schema names are missing, seed/register the schema in that process; rebuilding is only
needed after Python API changes.