Troubleshooting and Development EN

English · 简体中文

Troubleshooting and development

Send errors

Symptom	First checks
PacketHeaderError	Nonempty payload starting with 0xfe; every batch member valid
PacketSizeExceedMTU	Mode's fragmentation support, negotiated MTU, fragment count and budget
Send keeps waiting	Peer reading, reliable acknowledgements, unbounded pending application tasks
ConnectionClosed	Peer exit, explicit close, invalid/excessive receive state, stalled fragments
Connection timeout	Address, namespace, UDP port, active listener and RakNet version

set_loss_rate() simulates loss in the send path. It is not equivalent to netem's bidirectional packet/ACK loss and does not replace a full fair benchmark.

Lower throughput or higher latency

1. Confirm optimized builds and record the exact source revision, lockfile and toolchain.
2. Compare ordinary and batch APIs on fresh connections. Confirm two messages fit the MTU.
3. Inspect UDP receive errors and qdisc counters; socket overflow is not a healthy loss-free path.
4. Check CPU hotspots, workers, shard distribution, application queues and slow receivers.
5. Measure sustained-load and sparse latency separately. Warmup RTT is not burst RTT.
6. Examine ranges and increase repetitions before interpreting small changes.

Effective NACKs or retransmission timeouts disable coalescing for the connection's lifetime. Two 800 B messages do not fit together at the default MTU, and batch APIs do not guarantee better performance.

Bedrock connection timeouts

Try the backend directly before the proxy. If direct access fails too, check matching game versions, transport=raknet, RakNet version, ports, account/game services and network placement. A client error titled “NetherNet” alone does not identify the actual transport; capture full error details and server logs.

If only the proxy fails, inspect its frontend MOTD protocol/version, the port used by the client, upstream connection logs and forwarding in both directions. Receiving a server-list MOTD does not prove game login succeeded.

Development workflow

Edit an isolated copy with task-specific HOME, Cargo/Go caches, toolchains, target directory and network namespace. Do not change host shell files, global Git configuration, routing or qdisc.

For changes to ARQ, ACK/NACK, ordering, fragmentation or batching, cover:

• Loss, duplication and reordering semantics for all five modes; sequence wraparound and multiple channels.
• Existing RakNet wire formats, offline handshake versions, MTU negotiation and peer interoperability.
• Reassembly limits, backpressure, cancellation/shutdown and concurrent flush notifications.
• Ordinary and batch paths separately, including fallback after loss.
• Throughput, tail latency and RSS on the same revision; one improved metric is not a full evaluation.

Test entry points include unit tests, tests and interoperability instructions. When verification is needed, run cargo test inside isolation and prepare peers as described. Network tests must not fall back to the host.

Real Bedrock validation includes direct/proxied connections, world entry, movement and block interactions. Record endpoint builds and the RakNet handshake version. Transport echo benchmarks measure performance and do not replace real game compatibility checks.

Reporting an issue

Include library version/revision, OS, Rust/Tokio versions, negotiated MTU/version, API/mode, a minimal reproduction and sanitized logs. For performance issues, include complete parameters, repeated ranges and network counters. Do not upload account tokens, passwords or private world data.

Issues · Benchmark methodology

Blocking API · API index · Errors and deadlines

Complete feature checks (1.4.0)

Inside the isolated source environment, python scripts/test-features.py --list prints the matrix. python scripts/test-features.py runs all eight combinations of the three optional features, with cargo test --all-targets and doctests for each. Python 3.11+ is required for tomllib; CI selects 3.12. Use --offline only with dependencies already downloaded into the task cache.

CI also checks formatting, proxy tests with default/all features, leaf example builds and package creation. Linux-only APIs need cfg guards. Keep regression assertions about delivery, recovery and shutdown when adapting tests to platform scheduling; a longer timeout must not replace the asserted behavior.