GuidedPathNetworkException

Thrown when a guided path network cannot be constructed, or cannot be initialized for a replication, because its specification is inconsistent.

This signals a user specification error rather than a programmer error: the modeler has described a network that cannot exist. Argument and receiver-state violations by calling code remain ordinary IllegalArgumentException and IllegalStateException.

The exception is raised in two places. At network construction it reports geometry violations, malformed spurs, duplicate names, and alias collisions. At replication initialization it reports vehicle placements that overlap or that do not fit where they were placed. Rejecting a network eagerly, at the point of description, is a deliberate design choice: the alternative is an arithmetic failure part way through a long run, which is far harder to diagnose.

Every message names the offending element and the values that make it invalid, so that a modeler can act on the message alone without reading a stack trace. Build messages with the companion factory functions rather than composing text at the throw site, so the wording stays uniform and so the validation tests can assert against one definition of each message.