# Troubleshooting

## ID-only dialing returns `:resolution`

An endpoint ID has no network path. Use `:n0`, configure a static `address_book`,
or share an endpoint address or ticket. Direct/custom profiles never silently
fall back to public lookup.

## A direct endpoint is not reachable

Inspect `Endpoint.bound_sockets/1` and `Endpoint.addr/1`. Loopback addresses work
only on one host. Firewalls, NATs, and stale tickets can prevent direct paths.
Enable an appropriate relay rather than assuming a local direct test proves NAT
traversal.

## A custom endpoint never becomes online

Check relay readiness, URL, TLS policy, and bearer admission. `await_online/2`
means a relay handshake completed; it intentionally times out when a token is
wrong. Tokens are redacted, so compare deployment configuration at its source.

## A peer cannot accept an opened stream

QUIC streams are lazy. Send data on the new stream before waiting for the peer to
accept it. Check uni/bi direction and negotiated ALPN.

## `:busy` is returned

Another mutable operation owns the same stream half or configured accept/datagram
slot. Wait for, cancel, reset, or stop that operation. Opposite stream halves are
independent.

## `Distribution.start/1` rejects VM startup

Dynamic distribution requires an unnamed OTP 29 VM launched with
`-proto_dist iroh -no_epmd`. Early named startup requires the complete
`:iroh_beam, :distribution` environment in boot-time `sys.config`; a later
runtime provider cannot repair an already failed kernel distribution start.

## A configured distribution peer does not connect

Check each layer in order: Iroh relay/direct reachability, exact endpoint ID,
source/target node-name binding, and the Erlang cookie. `peer_info/1` reports the
expected authenticated ID and selected path but deliberately omits cookies and
relay tokens. Static peer changes require a full dynamic distribution restart.
After a netsplit or relay outage, explicitly call `Node.connect/1`; no membership
or automatic reconnect policy is included.

## Precompiled NIF cannot load

Verify the runtime is one of the documented targets, NIF 2.16 is supported, and
the downloaded archive matches `checksum-Elixir.IrohBeam.Native.exs`. Set
`IROH_BEAM_BUILD=1` only on a host with Rust 1.91 when intentionally building
from source.