#Troubleshooting map

This page maps common IndexBus symptoms to the best repo docs and rustdoc entry points.

Use it as the shortest path from “something is wrong” to the right contract or implementation surface.

#Region will not validate or attach

Start with:

• ../spec/v1-failure-lifecycle.md
• ../reference/v1-layouts.md
• indexbus_abi
• indexbus_core
• indexbus_transport_shm

Typical symptoms:

• header/layout mismatch,
• truncated mapping,
• wrong capability bits,
• initialization never reaches the ready state.

#Router is not moving traffic

Start with:

• v1-triage.md
• router-counters.md
• indexbus_route
• indexbus_core

Typical symptoms:

• source queue depth grows,
• routed/sec stays flat or absent,
• fanout behavior differs from expectation.

#Consumers are falling behind or drops are increasing

Start with:

• router-counters.md
• performance-tuning.md
• v1-triage.md
• indexbus_route
• indexbus_wake
• indexbus_blocking

Typical symptoms:

• consumer queue depth rises continuously,
• drops/sec, drops_full/sec, or drops_all_full/sec rises,
• CPU usage and latency trade off badly under load.

#Envelope or typed-message decoding fails

Start with:

• ../reference/indexbus-msg-v1.md
• ../spec/v1-semantics.md
• indexbus_msg
• indexbus_typed
• relevant codec crates under /rustdoc/ such as indexbus_codec, indexbus_codec_serde, indexbus_codec_rkyv, or indexbus_codec_sbe

Typical symptoms:

• invalid envelope magic,
• payload-length mismatch,
• producer and consumer disagree on schema/type/version,
• codec-specific decode failures.

#You know the layer, but not the crate

Start with:

• ../guides/crate-groups.md
• ../architecture/overview.md

Typical symptoms:

• confusion about whether a problem lives in substrate, kit, or platform,
• uncertainty over whether to debug a spec/ops issue or a crate/API issue first.