ASTARGRID_START_SOLID
Signal: The unit begins on a cell that is outside the grid or no longer walkable.
Diagnostic: Report the start cell before search and keep it separate from route failure.
Failure-Mode Museum
Every failed route should have a name.
The museum is the catalog behind the PathForge diagnostics demo. It keeps the common Godot grid-navigation failures explicit, testable, and reusable across articles, videos, and demo scenes.
GOAL_INVALID
Signal: The target cell is outside the grid, occupied, or forbidden by terrain.
Diagnostic: Separate impossible targets from solvable paths that merely need a different route.
GOAL_SOLID
Signal: The target cell is valid but marked solid for the current AStarGrid2D grid.
Diagnostic: Reject before search, especially when allow_partial_path would scan far more of the grid.
ASTARGRID_POINT_DATA_RESET
Signal: A shape-changing AStarGrid2D.update() made walls or weight_scale values disappear.
Diagnostic: Keep obstacle and weight data outside the grid, then replay it after shape updates.
INSUFFICIENT_CLEARANCE
Signal: A larger grid agent or baked navmesh radius tries to pass through a corridor built for a smaller unit.
Diagnostic: Show required clearance beside available clearance at the failing bottleneck.
DISCONNECTED_REGION
Signal: Both endpoints are valid, but they live in different connected regions.
Diagnostic: Name the region split instead of making the developer inspect every wall.
UNSYNCED_NAVIGATION_MAP
Signal: A NavigationServer2D query runs before the map has a synced iteration.
Diagnostic: Return the map iteration fact instead of calling the result no path.
REGION_BAKE_MISSING
Signal: The map has synchronized, but there are no usable navigation regions.
Diagnostic: Distinguish a missing or unbaked region from a first-frame sync wait.
DYNAMIC_BLOCKER_CHANGED
Signal: A door, tower, unit, or runtime object invalidates an otherwise valid path.
Diagnostic: Identify the runtime blocker and the local update that changed the grid.
Open diagnostics workbench
Switch between the same failure reasons in the lightweight interactive playground.
Read the failure-modes article
The full taxonomy behind these cases: every named reason a Godot path comes back empty.
Download Godot scene
Inspect the development diagnostics scene that backs the first corpus technical post.
Read benchmark lab
See the measured micro-benchmark and the policy for larger benchmark scenes.