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: 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.
• 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 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.