> Source: https://nexusatlas.dev/limitations — Nexus Atlas developer documentation (Getting started). Converted from the HTML page; the page is canonical.

# Known limitations

This page exists because the fastest way to lose an engineer's trust is to let them discover a boundary the documentation didn't mention. These are the edges of the current release, stated as plainly as the features are — design around them, and when one of them blocks your integration, say so in your [access request](https://nexusatlas.dev/request-access): this list doubles as a prioritisation signal.

## Data path

- **The inner tunnel is IPv4-only.** IPv6 works on the *underlay* — links may bind v6 addresses and peers may have v6 endpoints — but IPv6 packets inside the tunnel, and IPv6 `allowed_ips`, are not supported today.

- **No protocol version negotiation.** Mixed protocol versions between nodes fail loudly rather than interoperating. Treat fleet upgrades as coordinated events; see [compatibility rules](https://nexusatlas.dev/releases#compatibility).

- **Redundancy modes spend real bandwidth.** `broadcast` and the mirror escalations cost N× airtime by design; the receiver deduplicates, but the spectrum is spent.

- **Two links on one device and address must use distinct ports** — otherwise the kernel load-balances inbound datagrams between the sockets and each link loses half its traffic. Config validation enforces it; the [architecture page](https://nexusatlas.dev/docs/concepts/architecture#links-and-endpoints) explains why.

## Mesh & peers

- **Multi-hop mesh forwarding is hop-by-hop encrypted, not end-to-end.** An Atlas node relaying between two others decrypts and re-encrypts — it can read the traffic it forwards. Trust your relay nodes with the payload or encrypt above the tunnel. (Traversal relay *servers* forward opaque envelopes and cannot read them — the two kinds of "relay" have opposite properties.)

- **Runtime-discovered peers expire** after `[mesh] expiry_secs` (default 60 s) of gossip silence, destroying their sessions and punched endpoints; under the default `static` auth provider an expired discovered peer cannot re-add itself. Configured peers are exempt — they are marked unreachable and kept. Size the expiry generously in discovery-driven fleets.

- **Relay forwarding is capped at 8 hops.**

- **One routing layer at a time:** do not run Atlas mesh routing on top of a radio-layer mesh over the same nodes — two control loops re-routing the same failures fight each other.

## Traversal

- **Hard-NAT pairs stay on the relay.** Atlas does not attempt port-prediction punching; a pair of endpoint-dependent NATs relays indefinitely — correct, but some theoretically punchable pairs remain relayed.

- **NAT classification requires two observation IPs.** A single-address STUN setup cannot classify the NAT behaviors that predict punch success; Atlas relays answer on two addresses for exactly this reason.

- **Punched paths report as `direct`** in stats — there is no distinguishing marker yet, and the routes view does not name the relaying next hop.

## Transport classes

- **FEC does not pay on two-link bonds.** Surviving a link's death forces the parity floor to ~100% overhead there — the price of plain duplication, which is the simpler tool at that price. FEC's fractional-overhead benefit begins at three links. The daemon computes and reports the effective overhead rather than letting a nominal figure under-protect.

- **Fragments of one packet ride one link, always.** Cross-link distribution is per packet (Aggregate) or per shard (FEC), never per fragment — striping fragments would multiply loss.

## Operations

- **Keyfile revocation stops *new* sessions.** An established session lives until its next rekey (default interval 120 s). Tighten the rekey interval if eviction latency matters to your threat model.

- **Quotas are cost controls, not kill switches.** An over-budget link still carries traffic when it is the last usable path — deliberately.

- **A few knobs need a restart:** notably the traversal netcheck cadence and the gossip interval are read at engine construction; the commit-confirmed apply cycle handles the restart safely, but they are not hot knobs.

- **Terrain-aware link analysis exists as a library, not a wired feature.** The line-of-sight/Fresnel/diffraction math is implemented and tested; scheduler and routing integration is future work — do not design against it yet.

- **`disable_encryption` is a benchmarking mode.** Both peers must set it; it exists for performance measurement and nothing else.

## Platform

- **Linux is the supported platform.** The Android port (same engine inside a `VpnService`) is in active development and not yet a published production release.

- **Verification context:** traversal behavior is proven against simulated carrier-NAT topologies and on production relay hardware; degraded-link behavior is validated with injected loss, delay and link-kill emulation on real multi-radio testbeds. Design your acceptance tests to reproduce *your* failure modes on *your* bearers — we will help you scope them.