MeshCore Path Hash Modes Explained: 1, 2, and 3 Byte

If you’ve been running MeshCore for a while, you’ve probably seen path.hash.mode in the CLI and wondered what it actually does. Maybe you noticed it show up in the v1.14.0 changelog as “multibyte path hash support” and moved on. Or maybe you’ve been dealing with weird routing issues. Messages delivered to the wrong repeater. Paths that build fine one day and break the next. And you didn’t realize the problem was baked into the math.

This is the part of MeshCore most people skip over because it sounds abstract. It’s not. Path hashes are how your packets find their way across the mesh, and the size of those hashes determines whether your network can scale beyond a few dozen repeaters without stepping on itself.

We’ve been running MeshCore across our own network and watching the multibyte rollout play out in community meshes. Here’s how it works, when it matters, and how to know when your mesh has outgrown the default. If you’re brand new to MeshCore, start with the getting started guide first. This post assumes you’re already running nodes.

What Path Hashes Actually Do

Every time a packet floods through the mesh, it picks up breadcrumbs. Each repeater that forwards the packet appends a short identifier (its path hash) to the packet’s path field before rebroadcasting. By the time the packet reaches its destination, the path field contains a complete trail of every repeater it touched along the way.

That trail is the whole point. When the destination device sends a reply, it doesn’t need to flood the network again. It already has the route. The path field from the incoming packet tells it exactly which repeaters to use, in order, to get back to the original sender.

This is what makes MeshCore’s routing fundamentally different from flood-only systems. The first message floods. Every message after that follows the learned path directly. No redundant retransmissions. No wasted airtime. The path hash is what makes that direct routing possible.

So What Is the Hash

Each repeater’s path hash is the first N bytes of its public key. Not a hash of the path itself. A hash of the repeater’s identity. It’s a truncated fingerprint that fits inside the packet without burning through your entire payload budget.

The question is how many bytes you use for that fingerprint. That’s what path.hash.mode controls.

• 1-byte mode (path.hash.mode 0). Each repeater is identified by a single byte, the first byte of its public key. That gives you 254 usable IDs (0x00 and 0xFF are reserved).
• 2-byte mode (path.hash.mode 1). Two bytes per repeater. 65,536 possible IDs.
• 3-byte mode (path.hash.mode 2). Three bytes per repeater. Over 16 million possible IDs.

The path field in a MeshCore packet caps out at 64 bytes. Since each hop takes up N bytes of that space, the hash size directly controls how many hops a packet can traverse.

That’s the tradeoff. More bytes per hop means better identification, but fewer total hops before you run out of path space.

Why 1-Byte Mode Breaks at Scale

With 254 usable IDs, collisions aren’t just possible. They’re mathematically inevitable once your mesh grows past a certain size.

Think about it this way. If you have 20 repeaters, the odds of two sharing the same first-byte prefix are already meaningful. At 50 repeaters, it’s more likely than not. Beyond 100, collisions are guaranteed across most networks.

Collisions aren’t just a cosmetic problem. When two repeaters share the same 1-byte hash, both of them will match on direct-routed packets aimed at that prefix. Repeater A sees a packet with its hash at the front of the path, strips it off, and forwards the packet, even though the path was built through Repeater B. The packet goes the wrong direction. The sender never gets a reply. Or worse, both repeaters forward the packet, and you get duplicates bouncing through the mesh.

The Czech Republic mesh ran into this hard. Their network exceeded 255 repeaters in early 2026, more unique nodes than 1-byte mode can even represent. The community discussions on GitHub (#1613) laid out the geometry. A repeater with 50 km range covers roughly 7,800 km². With only 256 identifiers spread over that area, each ID covers about 30 km², a circle with a 3 km radius. In any populated area, that’s not enough separation.

Before multibyte support existed, the workaround was manual coordination. Ottawa’s mesh maintained a spreadsheet of all 256 IDs. Operators used keygen tools to generate public keys with specific first-byte prefixes. Some communities reserved entire blocks of the ID space for backbone links. It worked, barely, and only because people were paying attention. It was never going to scale.

How the Packet Encodes It

The path information lives in a single path_length byte, bit-packed:

• Bits 0 to 5. The hop count (0 to 63).
• Bits 6 to 7. The hash size, encoded as (hash_size - 1).

So 0b00 in the upper bits means 1-byte hashes, 0b01 means 2-byte, 0b10 means 3-byte.

A few examples:

• 0x05 = 5 hops, 1-byte hashes = 5 bytes of path data
• 0x45 = 5 hops, 2-byte hashes = 10 bytes of path data
• 0x8A = 10 hops, 3-byte hashes = 30 bytes of path data

This encoding means the receiver always knows how to parse the path. It reads the hash size from the upper bits and the hop count from the lower bits. No ambiguity. No negotiation.

Signs Your Mesh Has Outgrown 1-Byte Mode

You won’t always get a clean error message. Hash collisions create symptoms that look like other problems. Here’s what to watch for.

Messages that work one day and fail the next. If a direct-routed path works sometimes but randomly drops, a collision might be causing packets to route through the wrong repeater intermittently, especially if repeaters go on and off or conditions change which nodes are reachable.

Paths that build through unexpected repeaters. If your network tools show packets taking routes that don’t make geographic sense, two repeaters with the same 1-byte hash might be confusing the path builder.

Acknowledgments that never come back. You send a direct message, the path looks correct outbound, but the ACK never returns. A collision on the return path means a different repeater claims the packet and forwards it somewhere it can’t reach you.

Growing repeater count. This is the simplest signal. If your regional mesh has more than 30 to 40 repeaters within range of each other, collisions are statistically likely. Past 80 to 100, they’re almost certain. You don’t need to wait for symptoms. The math tells you it’s time.

Network mapping tools show ambiguous routes. Tools like the LetsMesh Analyzer and MeshMapper rely on path hash data to trace routes. With 1-byte collisions, these tools can’t reliably distinguish between two same-prefix repeaters. If your maps look wrong, this might be why.

Your community is coordinating first-byte prefixes by hand. If operators are picking keys to avoid collisions manually (the kind of thing covered in our repeater setup guide), that’s the clearest sign the system needs a bigger address space. Multibyte mode replaces the spreadsheet with math.

How to Switch

Check your firmware

Multibyte path hash support requires firmware v1.14.0 or later on all repeaters in the path. This is the hard constraint. Repeaters running older firmware will silently drop 2-byte and 3-byte packets. No error, no NACK, they just disappear.

Before switching your companion device to a larger hash size, confirm that the repeaters you depend on are updated. If even one critical repeater in your path is on pre-v1.14 firmware, your messages won’t make it through.

Repeaters on v1.14.0+ will forward all three hash sizes regardless of their own path.hash.mode setting. The mode only controls what size the repeater uses in its own adverts. This means you can upgrade repeaters progressively without worrying about intermediate states.

Set it on your repeater

Connect via USB serial or the web config tool (see the full CLI reference for setup) and run:

set path.hash.mode 1    # 2-byte hashes

Or for 3-byte:

set path.hash.mode 2    # 3-byte hashes

Check the current setting with:

get path.hash.mode

After changing the mode, send a new advert so the network learns your updated hash:

advert

Set it on your companion

In the MeshCore app (v1.41.0+), go to Settings → Experimental Settings and change the preferred path hash size. The app also shows path hash info on contact detail screens so you can see what size each contact is using.

The transition period

During migration, expect a mixed network. Some repeaters will advertise 1-byte hashes, some 2-byte. This is fine. v1.14.0+ repeaters forward all sizes. The risk is only with pre-v1.14 hardware that can’t handle the larger packets.

The practical migration path:

1. Update all repeaters to v1.14.0+ firmware first
2. Switch repeaters to path.hash.mode 1 (2-byte) as you update them
3. Once the critical mass of repeaters is on v1.14.0+, switch companion devices
4. Monitor for any paths that break. Those point to repeaters that still need updating.

Which Mode Should You Choose

Stick with 1-byte if your mesh is small (under 30 repeaters in range), you depend on very long hop chains (40+ hops for backhaul), or your region hasn’t finished upgrading repeaters to v1.14.0+. There’s no reason to rush if collisions aren’t a problem yet.

Go with 2-byte for most networks. It’s the community-recommended sweet spot. You go from 254 IDs to 65,536, enough for any foreseeable regional mesh, while only dropping max hops from 64 to 32. The vast majority of real-world paths stay under 25 hops. Unless you’re running extreme long-haul backhaul links across Australia, 32 hops is plenty.

Consider 3-byte only for very large-scale deployments with hundreds or thousands of repeaters in dense areas where even 65k IDs might eventually collide. The 21-hop limit is a real constraint, so make sure your network topology supports it before going there.

For NodakMesh and most community meshes in North America, 2-byte mode is the move. Our repeater infrastructure is on v1.14.0+, our hop counts are well under 32, and the collision headroom lets us grow without worrying about ID coordination.

The Bigger Picture

Path hashing is one of those details that doesn’t matter at all until it suddenly matters a lot. A mesh with five repeaters and 1-byte hashes works perfectly. A mesh with 80 repeaters and 1-byte hashes has invisible routing bugs that are almost impossible to diagnose without knowing about collisions.

The introduction of multibyte path hashes in v1.14.0 was one of the most important scaling changes MeshCore has made. It doesn’t add new features. It removes a ceiling. For any community mesh that’s serious about growing, removing ceilings early is always cheaper than dealing with the problems they create later.

If you haven’t checked your path.hash.mode yet, now’s a good time. Run get path.hash.mode on your repeaters. If they’re on 0 and your mesh is growing, consider switching to 1. The change takes one command, the improvement is permanent, and the failure mode of not switching gets worse with every repeater you add.

For more on how MeshCore routing works under the hood, see our MeshCore explained guide. If you’re building new repeater infrastructure, the solar repeater build guide covers hardware, power, and deployment.