I've noticed a lot of complaints, both here and on the GetSatisfaction site, about portals and how travel using them is a bit bugged at the moment. So in this thread I'm going to complile my knowledge about how portals work, and also list some of the common issues people encounter when using portals, and describe how to fix them and why the fix works.
(Note: I have not looked at the code or anything like that. All these observations come from my repeated experiments with portal placement, and all numbers given are a "best guess" based on these experiments.)
1. Portals: How do they work exactly?
1.1: The Nether-Overworld relationship
As most of us here know, the Nether is a compressed plane when compared to the Overworld. Specifically, the ratio between the two is 8:1. So for every 8 blocks moved in the Overworld, is the equivalent of moving 1 block in the Nether. This 8:1 factor only exists in the horizontal (x and z) directions. The vertical (y direction) is pretty much irrelevant when dealing with portal travel. If you have a working set of two-way portals, you can shift either of them any amount in the y direction, and they will still work.
1.2: The Co-ordinate system
Wherever you are in MineCraft, you can hold F3 to see debugging data. Amongst this, and relevant to our portal-placing interests, is your current position in Cartesian co-ordinates, centered on your head (although as mentioned, vertical doesn't really matter for portal placement). Once again, rememmber that the y axis is vertical, and the x and z co-ordinates relate to the two horizontal directions. Using these co-ordinates is how we build portals in "proper" locations in order to get them to link correctly.
1.3: What happens when you enter a portal?
When you step into a portal, the game first performs a search for nearby, activated, portals to connect to. Eg, unlit frames of obsidian will not be reactivated and linked to. Instead, the frame will be treated as an obstruction (more on this later), and a new portal will be generated. This search range is 128 blocks in both horizontal directions. This search range is the same regardless of which world you're portalling to. Keep this in mind as it's a cause of one of the bugs we'll meet later. =D
If the game cannot find any existing portals to link to, then it will try and attempt to create a new one, preferably in the "ideal" location found by taking the Overworld (X, Z) co-ordinates and dividing them by 8. However the game will only create portals on flat surfaces, not against cliffs, in Netherrack, and not floating above lava lakes. In these cases the game will shift from the "ideal" and place a portal nearby. This obviously shifts the co-ordinates, which is why the search range covered above is necessary, in order to account for any possible portal shifting.
2. Help! My portals don't work!
So far there are only 3 major issues with portals I see people reporting. If you have any others, please post them and I will do my best to try and come up with an explaination and fix. I will also then add it to the post.
2.1: "I entered my portal and reached the Nether fine, but when I came back, I emerged from a completely different portal!
The explaination: Let's go back to what was said about the portal search ranges. When going back to the Overworld from the Nether, the game will search a 128 by 128 area of space. This is equivalent to a small 16 by 16 area in the Nether, or a single chunk.
So what has happened here is, your original portal was relocated due to bad terrain in the Nether, and it was relocated more then 16 Nether blocks away. This caused the original Overworld portal to be outside the search range, resulting in the creation of this new, random portal.
The solution: You'll have to work out where the Nether-side portal "should" be, using the Overworld co-ordinates and calculating the spot yourself, and create it there. In the ideal case, this will be levelling a rough patch of Netherrack. However, do to the relatively large amount of relocation required, it is more likely that their is no terrain near where your portal would be, and the game instead adjusted to the nearest landmass. Otherwise, you may have to move your Overworld portal instead.
I'll take an example I encountered quite recently:
Overworld Portal built at (-556, 304)
Expected Nether Portal at (-69 or -70, 38)
Actual Nether Portal at (-69, 21.5)
As you can see, the Nether portal was in the correct x co-ordinate, but had been largely shifted in the z. 17 blocks away to be exact. This caused be to emerge on the beach, a short distance away from my house =\. The reason for this: A giant lava lake right in the middle of where it should have been. However, upon building out a platform to the ideal location and manually creating the portal, the gates worked fine.
2.2: I made my first portal in the Overworld, and it links to the Nether and back fine. But now I've created a second gate in the Overworld, and it just links me back to my first Nether portal! WTF?!
The explaination: Again, it's a problem with the search ranges. Remember that it is the same 128 blocks in either world. 128 by 128 blocks in the Nether is equivalent to 1024 by 1024 blocks in the Overworld. Meaning if the distance between your two portals is less then that in the Overworld, it will find the already-existing portal in the Nether while searching, and link to that without even attempting to make its own counterpart.
The solution: Most people would tell you to, again, pull out the pickax and calculator, and manually build one in the correct spot. However, a nifty trick I prefer to use, is as follows:
1) Portal into the Nether, and remove and obsidian block from the frame of your gate, causing it to deactivate.
2) Suicide in order to get back to the Overworld.
3) Enter the gate that was NOT two-way, or the one that linked to the incorrect gate.
Now, when the game does the search, the deactivate frame will not be registered. This will cause it to create one instead, which should link to the Overworld gate properly. Now you can replace the Obsidian Block and relight your first gate, and both your gate pairs will work properly. =D
2.3: I was walking around in the Overworld, and I found a portal on the surface, and it was was already activated! Is this normal?
The explaination: When you die in the Nether, you have to be moved to the Overworld, in order to get back to the spawn point. When the game moves you between the worlds, it runs the portal code again, treating the point you died as the "entry portal". Unless you're in range of another existing portal, this will result in a new portal, where you "exit" from before being taken back to spawn.
The gate you found is the result of one of these Nether deaths. Unless you were wandering a severely long way in the Nether, it will likely just link back to one of one of your existing Nether portals.
The solution: Just destroy it, it's free Obsidian. =D