A question about APISIX route prioritization

[Lewisyixin]

I encountered an issue while using APISIX regarding route prioritization. Suppose there are two identical routes, A and B. Route A was created first, so it initially has a higher priority. However, after reloading APISIX, route B suddenly takes precedence.

After reviewing the source code, I came to a preliminary conclusion: when APISIX reloads, it rebuilds the entire route radix tree based on the data from etcd. The prioritization appears to be determined by the route IDs. In our case, the route IDs are custom-generated, and since the ASCII value of B comes before A, route B ends up with higher priority after reload.

My question is: is my understanding correct? And is this behavior part of APISIX's intended design? If so, does it mean that when we generate custom route IDs, we must ensure their order reflects the desired priority to avoid unexpected results in certain edge cases?

[dosubot[bot]]

Your understanding is correct. When APISIX reloads, it rebuilds the route radix tree using the data from etcd, and if two routes are otherwise identical, the order in which they are inserted—often determined by their route IDs—can affect which one takes precedence. This is an intentional design choice to ensure deterministic behavior when priorities and match criteria are equal. If you use custom route IDs, their ASCII order can influence priority after reloads, so you should ensure your ID scheme reflects your intended route precedence if you want to avoid surprises in these edge cases. Explicitly setting the priority field on routes is the recommended way to control matching order when possible. There is currently no explicit documentation warning about this, but the codebase logic supports this behavior source.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[Lewisyixin]

But doesn’t this pose a potential risk?

As in the scenario I described earlier: when route B was created after route A, it initially had a lower priority. However, after an APISIX reload, route B unexpectedly gains higher priority than A. From a design perspective, this feels a bit inconsistent or even counterintuitive.

Wouldn’t it make more sense if APISIX sorted routes by creation time when reloading the full configuration from etcd? That way, the original creation order (and therefore the original priority) could be preserved more reliably.