How Portal Linking Actually Works

Verified: Java 26.3 / Bedrock 26.50 · 2026-09-16 · search ranges differ by edition · Updated 2026-09-16

Portals are not married to each other. Every time you step through one, the game computes a target in the destination dimension, hunts for the nearest lit portal within a fixed range of it, and sends you to whatever it finds — or builds one if it finds nothing. Once you see the hunt, every "my portal broke" story becomes a geometry problem the portal calculator can solve.

The hunt, step by step

Step one: convert. Your position's X and Z are divided by 8 (entering the Nether) or multiplied by 8 (entering the Overworld), floored, Y untouched — the arithmetic covered in the travel-math guide. Step two: search. Around that computed target the game scans a square region for existing lit portal blocks — on Java, a 16-block radius when arriving in the Nether and a 128-block radius when arriving in the Overworld; on Bedrock, 128 blocks in both directions. The scan spans the full height of the world. Step three: choose. Among every portal block found, the game takes the nearest by straight-line 3D distance — height counts as much as anything horizontal. Step four, only if the search came up empty: the game builds a portal as close to the target as terrain allows, forcing a bare 2×3 obsidian platform in midair if it must.

Why the two Java numbers are secretly one number

Sixteen Nether blocks and 128 Overworld blocks are the same distance seen from the two sides of the 1:8 scale. Java's search is symmetric in world terms: a pair of portals either sees each other from both directions or from neither. Bedrock chose a different simplicity — 128 blocks everywhere — which makes its Nether-side search cover sixty-four times the area of Java's: eight times the radius, squared. Counted as the inclusive block spans the calculator prints — 257 on a side against 33 — the ratio comes out a shade over sixty. That is not a detail. A cluster of Nether portals spaced 30 blocks apart keeps to itself on Java and becomes one big raffle on Bedrock.

The four classic failures

The stolen link. A neighbor's portal — or your own older one — sits inside the search box and closer to the target than the portal you meant. Fix: put the intended portal exactly on the computed coordinates, or move the rival out of the box. The height loss. Two portals share a column; yours is 60 blocks below the target Y, theirs is 10 off horizontally but level with it. Theirs is nearer in 3D and wins. Matching Y is part of the build, not a nicety. The one-way link. Portal A sends you to B, but B computes a target nearer to portal C and sends you there. Round trips are only guaranteed when each side sits on its computed coordinates. The surprise portal. You step through before building the far side; the game finds nothing and pours a new portal near the target — occasionally on a forced obsidian platform over a lava ocean. Building both ends yourself, at the coordinates the calculator prints, removes every one of these from play.

The worked pair

An Overworld portal at 1000, 64, −1000 computes a Nether target of 125, 64, −125. Build there and the Java-side search box — X 109 to 141, Z −141 to −109 — contains exactly one portal: yours. Keep any second Nether portal more than 16 blocks from that target (on Bedrock, more than 128) and the link cannot wander. Coming home, the game scans X 872 to 1,128 and Z −1,128 to −872 around the Overworld anchor, and because one Nether column answers for an 8×8 Overworld area, anything you build from X 1,000–1,007, Z −1,000–−993 belongs to the same pairing.

Limits

This guide covers where portals send you, not portal construction, chunk loading, or entity cooldowns. Ruined portals and the End's gateways follow their own rules entirely. And the forced-platform behavior described above is the documented last resort — the terrain scan that precedes it has finer print than a travel guide needs.

Sources

Search ranges, target arithmetic, 3D-distance selection, and forced-portal behavior: the Minecraft Wiki's Nether portal documentation (minecraft.wiki/w/Nether_Portal), verified 2026-09-01 against Java 26.2 and Bedrock 26.x, and cross-checked against two other portal calculators that publish the same search boxes (minecraftmaps.com, craftmc.net). Every coordinate and range printed here is asserted in the calculator's test suite.