BGP route-map order troubleshooting is a small operational skill that prevents large routing surprises. A policy can look correct line by line, yet still produce the wrong result because an earlier sequence matched the route before the more specific rule was ever evaluated.
This is common on data center border leaves, internet edges, MPLS VPN handoffs and lab fabrics where engineers add a new exception to an existing policy. The neighbor comes up, prefixes are visible, but local preference, community tagging, route filtering or AS-path prepending does not behave as expected.
The fix is rarely to rewrite the whole policy. A safer workflow is to prove which sequence matched, understand why it matched, then make the minimum ordered change. This article fits with the Start Here networking topics, Data Center Networking, BGP Table Watch and Resources pages.
The problem: a valid route-map can still match the wrong rule
Most route-policy engines are ordered. They evaluate sequence numbers from lowest to highest and stop at the first matching clause. That behavior is useful when the policy is intentionally structured from specific exceptions to broad defaults, but dangerous when a broad permit or deny appears too early.
A typical symptom list looks like this:
- A customer, tenant or partner prefix is accepted, but it receives default local preference instead of the high-priority value.
- A route that should be tagged for traffic-engineering leaves the AS without the expected community.
- A deny sequence exists for unwanted more-specific routes, but those routes are still installed because a broad permit matched first.
- A route refresh or soft clear appears to make no difference because the policy logic, not BGP state, is the issue.
The important point is that BGP may be completely healthy. The session is established, updates are exchanged, next hops are reachable and the route is best. The failure is in policy intent versus policy order.
Design principle: exceptions first, defaults last
For an inbound BGP policy, start with the narrowest business or technical exception. Place route-specific local preference, community translation, blackhole acceptance, backup-path marking and security denies before broad customer or region-wide permits. The broadest permit should normally sit near the end, followed by an explicit deny or the platform's implicit deny behavior.
A clean mental model is:
- Reject known bad routes that must never be accepted from this neighbor.
- Permit and tag special routes that need non-default attributes.
- Permit normal routes from an approved aggregate or documented prefix-set.
- Deny everything else, with counters or logging if the platform supports it.
That order is especially useful at data center edges where BGP policy protects EVPN/VXLAN border connectivity, cloud on-ramps, internet breakout and WAN route exchange. It also gives an AI-assisted change-review tool a clear pattern to validate: more specific matches should not be hidden behind broader matches.
Diagnosis workflow: prove the first matching sequence
1. Capture the expected route and attributes
Pick one prefix that is wrong and write down what you expect. Use documentation prefixes in examples and keep production outputs sanitized in tickets or automation logs.
Prefix: 198.51.100.0/24
Neighbor: AS 65010
Expected: permit, local-pref 180, community 65000:210
Actual: permit, local-pref 100, no communityDo not start by clearing the session. First confirm whether the route is present before policy, after policy and in the selected RIB. On many platforms you can compare received-routes, advertised-routes, policy detail and route attributes without interrupting traffic.
2. Inspect prefix-list specificity
Prefix-list syntax is one of the easiest places to hide a bug. A rule for an aggregate with le may match far more than the engineer intended. A rule without le or ge may match only the exact aggregate and not its longer prefixes.
ip prefix-list PL-NORMAL seq 10 permit 198.51.100.0/23 le 24
ip prefix-list PL-SPECIAL seq 10 permit 198.51.100.0/24If PL-NORMAL is referenced by route-map sequence 10 and PL-SPECIAL is referenced by sequence 20, the /24 will never reach sequence 20. Sequence 10 already matched it.
3. Read route-map counters
Route-map hit counters are your best friend. They show whether the expected sequence is actually used. If counters increase on the broad sequence when a test route arrives, the problem is confirmed.
route-map RM-IN permit 10
match ip address prefix-list PL-NORMAL
set local-preference 100
!
route-map RM-IN permit 20
match ip address prefix-list PL-SPECIAL
set local-preference 180
set community 65000:210 additiveThe above policy is syntactically valid but logically wrong for the special prefix. The more specific sequence must appear before the broad one.
Implementation: a safer ordered policy
A safer structure puts the special case first, then the normal aggregate, then a final deny. Exact syntax varies between Cisco IOS/NX-OS, Junos, EOS, FRR and other stacks, but the ordering principle is the same.
ip prefix-list PL-SPECIAL seq 10 permit 198.51.100.0/24
ip prefix-list PL-NORMAL seq 10 permit 198.51.100.0/23 le 24
!
route-map RM-IN permit 10
description special route gets higher preference and tag
match ip address prefix-list PL-SPECIAL
set local-preference 180
set community 65000:210 additive
!
route-map RM-IN permit 20
description normal documented prefixes
match ip address prefix-list PL-NORMAL
set local-preference 100
!
route-map RM-IN deny 100
description deny anything not explicitly allowedFor IPv6, mirror the same policy structure with 2001:db8::/32 documentation examples in lab notes, and use the platform's IPv6 prefix-list or policy-statement syntax.
Change-control checklist
- Export the current route-map, prefix-lists and neighbor attachment before editing.
- Record pre-change counters for every affected sequence.
- Check whether the platform requires a route refresh, inbound soft clear or policy re-evaluation command.
- Limit the blast radius: one neighbor, one address family or one VRF at a time.
- Prepare rollback as the previous ordered policy, not as a vague instruction to remove the new lines.
In an automation pipeline, treat route-map sequence order as data. A pre-check can parse candidate prefixes and warn when a broader prefix-list appears before a more specific exception. This is a practical use case for Hermes or any AI-assisted network automation workflow linked from the AI Infrastructure & Automation hub.
Verification and troubleshooting after the fix
Verify route attributes, not just reachability
A successful ping does not prove the route policy is correct. Verify the attributes that the policy was supposed to change:
- Local preference or weight on the receiving router.
- Communities, extended communities or large communities.
- AS-path prepend behavior on advertised routes.
- Route-target import/export behavior for VPN or EVPN address families.
- Whether denied prefixes are absent from the RIB and visible in policy counters where supported.
# Generic verification notes
show bgp ipv4 unicast 198.51.100.0/24
show route-map RM-IN
show ip prefix-list PL-SPECIAL
show bgp neighbor 192.0.2.10 received-routes
show bgp neighbor 192.0.2.10 routesWatch for hidden interactions
If the route still looks wrong after reordering, check for a second policy point. Common examples are peer-group inheritance, address-family-specific route-maps, outbound policy on the other side, route-reflector policy, redistribution policy or VRF import policy. The wrong route-map may be fixed while another policy later overwrites the attribute.
Also confirm that counters were reset or interpreted correctly. A route-map counter from last week can mislead the troubleshooting process. Capture a baseline, trigger a controlled route refresh if allowed, and compare the delta.
Practical takeaways
- BGP route-maps are ordered; first match wins on most common platforms.
- Put exact exceptions before broad aggregate permits.
- Use hit counters to prove the matching sequence before changing production policy.
- Verify route attributes after the fix, not only neighbor state or ping reachability.
- Automate policy linting for broad-before-specific mistakes in data center and edge BGP changes.
Good BGP operations are not only about protocol knowledge. They are about small, repeatable checks that stop a simple policy-order mistake from becoming a traffic-engineering incident or an accidental route leak.
Post a Comment