When the Map Breaks the Robot

The robot is behaving strangely. It stops halfway down an open road. It refuses to turn at an intersection it has navigated a hundred times. It drifts toward a curb as if being pulled by a magnet. The logs say “planner failed to generate trajectory” or “no valid path found” or “velocity constraint violated.” None of these messages names the map. None of them points to a lanelet, a regulatory element, or a missing topological edge.

But the map is the cause. It always was. The robot is never wrong about the map. If it behaves strangely, the map told it to. This chapter is about hearing what the map is saying, and tracing the misbehavior back to the element that caused it.

The taxonomy

Map-induced failures fall into four categories. Each has a signature in the robot’s behavior, a root cause in the map, and a trail of evidence you can follow from the symptom back to the source.

Wrong lane: boundary misalignment

The symptom. The vehicle drifts within its lane, hugging one edge or oscillating between boundaries. On straight roads, it looks like a control problem. On curves, it clips the inside or runs wide on the outside.

The cause. A lanelet boundary that does not match the physical road edge. The boundary was traced from a pointcloud that predates recent construction, or it was drawn at the wrong resolution, or it was copied from a different lanelet and never adjusted. The boundary is geometrically valid and topologically connected. It is just in the wrong place.

Harbor Yard example. The main loop road at Harbor Yard is one-way, 3.5 meters wide. The team traced the right boundary along the curb line. Six months later, a new container pad was poured, extending the pavement by 80 centimeters on the right side. The pointcloud map was recaptured but the Lanelet2 map was not updated. The lanelet still had the old boundary, 80 centimeters inside the actual curb. The planner, reading the old boundary, generated trajectories centered in the old lane. The vehicle appeared to hug the left edge of the available pavement. It was not drifting. It was perfectly centered in a lane that no longer existed.

How to trace it. Load the pointcloud map and the Lanelet2 map side by side. Overlay the lanelet boundaries on the pointcloud. Where they diverge from the visible curb or road edge, you have found the boundary error. The fix is a single edit: move the boundary linestring to match the current geometry. The change propagates through the loader, the planner, and the trajectory generator without any other intervention. One edit, and the vehicle drives straight again.

Ghost stops: orphaned or misplaced regulatory elements

The symptom. The vehicle stops where there is no stop sign, no intersection, and no obstacle. It slows to zero, waits a moment, and then continues. The stop is brief, consistent, and reproducible at the same location on every run.

The cause. A regulatory element attached to a lanelet where it should not be, or a regulatory element whose referenced geometry was deleted without removing the regElem itself. In the first case, a stop line regElem was accidentally associated with a lanelet far from any actual stop line. In the second, a stop line linestring was deleted during a map cleanup, but the regElem that referenced it was not cleaned up. The regElem is orphaned: it exists, it is published by the loader, but the planner cannot find a valid refline and applies a default stop condition at the lanelet entry.

Harbor Yard example. The gatehouse at Harbor Yard has a legitimate stop line. During a map revision, the team added a second stop line regElem for a proposed pedestrian crossing near the warehouse entrance. The pedestrian crossing was never built, and someone deleted the crossing linestring during a later cleanup. The regElem remained. The planner encountered it on the approach lanelet, found no refline, and applied a zero-velocity constraint at the lanelet boundary. The vehicle stopped for no visible reason, precisely at the same spot on every run. The map file contained a single orphaned <regulatoryElement> tag, invisible in the editor unless you knew to look for it.

How to trace it. Open the Lanelet2 file and search for every regulatory element. For each one, verify that every referenced linestring, lanelet, or area ID still exists in the file. Orphaned references are the easiest map bug to find and the most embarrassing to ship. A five-minute grep of the .osm file catches them all.

Intersection hesitation: topology gaps

The symptom. The vehicle approaches an intersection, slows, and stops. After several seconds, it creeps forward and resumes. There is no stop sign and no traffic. The hesitation is consistent: the same intersection, the same behavior, every time.

The cause. A missing successor in the topology graph. Two lanelets that are geometrically adjacent do not have a declared topological relationship. The planner reaches the end of one lanelet and cannot find a legal successor. It stops, enters a fallback behavior that searches for a nearby lanelet within a distance threshold, finds the adjacent lanelet, and proceeds. The stop is the planner’s recovery from a topology gap.

Harbor Yard example. The Harbor Yard loop road approaches a T-junction where the dock access road branches off. The lanelet for the loop road approach has two successors: the continuing loop segment and the dock access segment. During editing, the dock access successor was deleted by accident. The lanelet now had only one successor. When the planner routed a vehicle to the dock, the route ended at the approach lanelet. The next lanelet on the dock access road was geometrically adjacent but not topologically connected. The planner stopped, searched, found it by proximity, and continued. The hesitation was three seconds of dead time in every dock approach cycle.

How to trace it. When the vehicle hesitates at an intersection, check the topology graph. Every lanelet must declare its successors. A geometric adjacency is not a topological connection. If the lanelet ends with no declared successor, the planner will stop, and the logs will record a routing gap. The fix is a single edge in the topology graph.

Curb strikes: missing or misclassified areas

The symptom. The vehicle’s wheels contact a curb, a planter, or a raised surface that appears in the pointcloud but not in the Lanelet2 map. The strike is low-speed and occurs during a maneuver the planner generated: pulling into a parking spot, navigating a tight loading dock approach, or turning around in a cul-de-sac.

The cause. A non-drivable area that is not marked as an area in the Lanelet2 map. The planner treats any space not inside a lanelet or an area as unknown, and it may generate trajectories through unknown space when no lanelet path exists. A curb, a planter, or a bollard that is not encoded as an area with a subtype is invisible to the planner.

Harbor Yard example. The container zone at Harbor Yard has a raised concrete planter in the center of the turnaround area. The planter appears clearly in the pointcloud. It was not traced as an area in the Lanelet2 map because the original map builder considered it “obviously not drivable.” The planner, asked to generate a turn-around path for the cargo tug, found no lanelet that described a turn-around. It planned a path through the unknown space, and the unknown space contained the planter. The vehicle struck it at 1 mph. The map did not say the planter was there. The planner did not know it existed.

How to trace it. When the vehicle strikes a static object at low speed during a planned maneuver, check whether that object is encoded as an area in the Lanelet2 map. If it is not, the planner had no way to avoid it. Trace it as an area with the appropriate subtype, and the planner will route around it.

The debugging protocol

When the robot misbehaves, follow the same three steps every time.

1. Identify the module that failed. What was the last error message before the misbehavior? Which subsystem emitted it: localization, planning, or perception?

2. Identify the map element that module consumed. What lanelet, regulatory element, or area did the module read immediately before it failed? The map element is in the Lanelet2 file. Find it.

3. Compare the map element to reality. Overlay the map element on the pointcloud. Does the geometry match? Are all references valid? Is the topology connected? If any of these is false, the map is the cause.

The protocol takes ten minutes and answers the question that log analysis alone cannot: was the robot wrong, or was the map? The answer is usually the map. The fix is usually a single edit. And the vehicle, on its next run, drives as if the error never happened. Because as far as the planner is concerned, it never did.

Try this

[15 min] Diagnose a map-induced failure from symptoms.

A cargo tug at Harbor Yard stops in the middle of the main loop, 15 meters past the gatehouse, with no stop line in sight. The logs say “velocity constraint violated.” There is no obstacle in front of the vehicle. It waits five seconds and continues at 2 mph for the rest of the loop.

1. Which subsystem enforces velocity? (Planning.)
2. Which map element carries the velocity constraint? (The speed limit regulatory element attached to the lanelet.)
3. Open the Harbor Yard Lanelet2 file. Find the lanelet that covers the segment where the vehicle stopped. Check its speed limit. Is it 2 mph? If so, the speed limit regElem is attached to the wrong lanelet.
4. Before you edit the tag, check one thing upstream: the map’s projector info. If the Lanelet2 map and the pointcloud map were projected differently, the vehicle’s localized position can land in the wrong lanelet, and a tug that believes it is in the dock approach (which really is 2 mph) slows down for a rule it is not under. A mistyped speed limit and a half-meter projection shift wear the same costume. The metadata check tells them apart.

You have just traced a ghost slowdown to its source in under five minutes. The same protocol works for every failure in this chapter. The robot told you the answer. You just had to ask the map.