Skip to main content

PTV xServer 2: HTTP 503 QueueOverFlowFault on XMap tile requests during map zoom interactions

Updated

Symptom

XMap tile requests return HTTP 503 with the following error:

$type: QueueOverFlowFault

hint: See core.queueSize in conf/xserver.conf

The error occurs on GET requests to /services/rest/XMap/tile/ with various layer combinations (background, transport, labels, PTV_TruckAttributes). Example affected requests:

GET /services/rest/XMap/tile/13/4213/2906?storedProfile=silkysand&layers=background,transport,labels&xtok=...

GET /services/rest/XMap/tile/13/4215/2907?storedProfile=silkysand&layers=labels,PTV_TruckAttributes&contentType=JSON&timeConsideration=SNAPSHOT&referenceTime=2026-06-24T02:54:21.518Z&xtok=...

The error is consistently reproducible when zooming or unzooming on the map. Multiple simultaneous tile requests are generated by the client during these interactions.

Cause

The xServer request processing queue is saturated. When a user zooms or unzooms on the map, the client triggers a large burst of simultaneous tile requests. If the number of pending requests exceeds the configured core.queueSize limit in conf/xserver.conf, the server immediately rejects the excess requests with HTTP 503 instead of queuing them.

Contributing factors:

  • Default core.queueSize value may be too low for the volume of concurrent tile requests generated by map interactions.
  • Insufficient number of xMap instances to process requests in parallel.
  • No client-side throttling or deduplication of tile requests during rapid zoom interactions.

Resolution

The following options can be applied independently or combined. Combining all three is recommended for a stable result.

Option A – Increase the queue size in xserver.conf
Edit conf/xserver.conf and raise the core.queueSize parameter. Example: increase from the default (25) to 100 or 200.
This reduces immediate rejections by allowing more requests to wait in queue before being processed.

Option B – Increase the number of xMap instances
In conf/xserver.conf, increase the number of xMap worker instances.
This allows more tile requests to be processed in parallel, reducing queue build-up.

Option C – Optimise client-side request behaviour

  • Limit the number of simultaneous tile requests issued during zoom/unzoom interactions.
  • Cancel or debounce in-flight tile requests that become obsolete when the zoom level changes rapidly.
  • Remove redundant requests for tiles already cached or not yet visible in the viewport.

Option D – Use asynchronous calls
Switch to asynchronous (Async) tile requests on the client side.
Note: async calls improve client-side responsiveness and reduce blocking, but do not reduce the total number of requests sent to the server. They must be combined with Options A–C.

The issue is resolved when zoom and unzoom interactions no longer produce HTTP 503 responses.

Related to