Quick answer: Metroidvania bugs cluster around persistent world state, ability gating that controls progression, sequence breaks that reach areas out of order, and map tracking. Capture the full progression flag set, the abilities unlocked, the current and previous room, and the player position so you can reproduce a soft-lock, a broken gate, or a map that lost track of the world.
Metroidvanias are built on a single interconnected world that the player slowly unlocks by gaining abilities, with doors and barriers that open only once the right power is acquired. That persistent, gated world is a beautiful design and a demanding one to keep consistent. A door that should have opened but did not, a sequence break that reaches an area the game was not ready to show, a save that loses a defeated boss, or a map that forgets a room the player explored, each can strand a player or quietly break their progression. This post covers the bugs specific to the genre and the context needed to reproduce them.
Persistent world state and the flag soup
A metroidvania remembers everything the player has done across one connected world: bosses defeated, doors opened, items taken, switches flipped, and shortcuts unlocked. That history lives in a large set of progression flags, and the world is reconstructed from them every time a room loads. Bugs appear when a flag is not set, set on the wrong condition, or read inconsistently between the room that writes it and the room that reacts to it. A defeated boss that respawns, a permanent door that closes again, or a collected item that reappears all come from flag mismanagement.
Because the world is rebuilt from flags, the only way to debug these is to see the flag set. A player reporting that a boss came back to life is describing a flag that failed to persist or to load. Capturing the full progression flag state with each report lets you compare it against what the player describes and find the flag that is missing or wrong. The flag set is to a metroidvania what the seed is to a roguelite: the compact encoding of the entire world's state that makes a confusing report concrete.
Ability gating that controls progression
Progression in the genre is gated by abilities: a double jump, a dash, a wall climb, each unlocks regions previously out of reach. The gating logic has to correctly check which abilities the player has before allowing or blocking passage. Bugs here directly stall progression. A gate that checks for the wrong ability traps a player who has the right one, or a barrier that fails to register a newly unlocked power leaves the player stuck staring at an obstacle they should be able to clear. These are progression-blocking bugs, the most severe class in the genre.
To debug a gating bug you need the set of abilities the player has actually unlocked and the specific gate or barrier they are stuck at. A player reporting they cannot get past a wall might lack the ability, in which case it is a guidance issue, or they might have it and the gate is checking wrong, in which case it is a real bug. Capturing the unlocked ability set alongside the room and the player position lets you tell those apart instantly and, if it is a bug, see exactly which ability check is misfiring.
Sequence breaks and out-of-order access
Skilled players love to sequence break, using clever movement to reach areas before the game intends. Designers often embrace this, but it stresses every assumption about the order content is seen. A sequence break can reach a boss room before the cutscene that sets it up has flagged, an area whose enemies were not meant to spawn yet, or a story beat out of order that leaves later dialogue nonsensical. The bug is not the break itself but the unhandled state it exposes.
These are hard to anticipate because they depend on reaching a place via an unintended path. The critical context is the player's progression flag state when they entered the area, since that reveals which expected prerequisites were skipped. A report of a broken cutscene in a late-game room, paired with a flag set showing an early-game progression, immediately tells you a sequence break exposed an unguarded assumption. Capturing the flags and the entry room lets you reproduce the out-of-order state and decide whether to support the break or gate it.
Room transitions and map tracking
The world is stitched together from rooms, and the transitions between them are a frequent bug source. A door that drops the player into the wrong room, a transition that spawns them inside geometry, or a load that fails and leaves them falling through the floor. The map system that tracks where the player has been is closely tied to these transitions, and it has its own bugs: a room explored but not recorded on the map, a marker placed in the wrong cell, or fog of war that fails to clear, leaving the player unable to navigate the backtracking the genre demands.
Debugging transitions needs the current room, the previous room, and the player position at the moment of the report. A player who fell through the floor on entering a room is pointing at a transition spawn point placed below the geometry, and the previous room tells you which doorway sent them there. For map bugs, capturing which rooms the player has visited against what the map shows reveals the cell that failed to record. Together, the room pair and the visited-room set make the world's connectivity bugs concrete and reproducible.
Setting it up with Bugnet
Bugnet's in-game report button captures game state automatically, and for a metroidvania the most valuable capture is the progression flag set paired with the unlocked abilities. When a player hits a stuck gate or a respawned boss, the report can carry the full flag state, the abilities owned, the current and previous room, and the player position. Instead of a screenshot of a wall and the words I am stuck, you get the exact world state, so you can tell a real gating bug from a guidance issue and reload the same flags to reproduce it.
Occurrence grouping is especially useful because a single broken gate or transition strands many players at the same spot. Grouping folds those reports into one issue with a climbing count and the shared room, so a progression-blocking bug surfaces as an urgent cluster rather than scattered tickets. Custom fields let you filter by room or by the abilities involved, so a gate checking the wrong ability shows up as everyone stuck in one place with the same power. That clarity is what lets you triage the progression blockers, the genre's worst bugs, first.
Testing a connected world
The hardest thing to test in a metroidvania is that the whole world stays consistent and completable from any reasonable progression state. The most effective practice is an automated reachability check: from a given flag and ability set, verify that the intended next objective is reachable and that no required gate is impassable. Run it across many progression states, including ones that simulate common sequence breaks, and it will catch the gates that check the wrong ability and the transitions that drop players into geometry before any player does.
Reinforce that with a feedback loop from captured reports. When a player's flag set reveals a soft-lock or a broken gate, encode that exact progression state as a regression test so the world can never strand a player there again. Because your reports carry the full flag and ability state, every soft-lock a player finds becomes a precise, reproducible scenario for your reachability suite. Over time that suite mirrors the real ways players move through your world, including the clever ones, keeping the interconnected map the genre is built on consistent across every patch.
The flag set is the world. Capture it with the unlocked abilities and the room pair, and a confusing soft-lock becomes a precise, reproducible scenario.