Skip to main content

Troubleshooting Asset Gateway and Compatibility

Summary​

This page covers routing and compatibility-shape problems. The gateway is a YARP proxy. An asset-routing feature flag routes only the asset slice to the asset-service. A shadow route and an X-Gateway-Route-Source response header, whose value is asset-service, asset-service-shadow, or monolith, help identify which backend served a request. Rollback is simply turning the flag off. Native and compatibility responses differ in shape, so comparing fields requires knowing which shape was returned.

Audience​

Support engineers, DevOps engineers, and developers investigating which backend served a request, unexpected response shapes, or behavior differences after a flag change.

Symptoms​

  • A request behaves differently than expected and the serving backend is unclear.
  • Response fields differ from what a caller expects.
  • Behavior changed after a routing flag change.
  • A shadow route is producing unexpected observations.

Cause​

Scope​

This page covers gateway routing, the route-source header, the routing flag, and compatibility-versus-native shape. Authorization at the edge is covered on the auth page.

Likely causes​

  • The asset-routing flag state determines whether the asset slice went to the asset-service or the monolith, changing behavior.
  • The response was a monolith-shaped compatibility projection while the caller expected the native shape, or the reverse.
  • The request was served by the shadow route, so its observations are shadow, not primary.
  • A recent flag change moved traffic between backends.

Resolution​

Safe diagnostics​

  • Read the X-Gateway-Route-Source response header to determine which backend served the request.
  • Confirm the asset-routing flag state for the environment.
  • When comparing fields, confirm whether the response is native or the monolith-shaped compatibility projection.
  • If behavior changed, correlate it with a flag change; rollback is turning the flag off.

Validation​

  • Confirm the route-source header matches the intended backend for the flag state.
  • Confirm the response shape matches the path used.
  • Confirm that turning the flag off returns traffic to the monolith path as expected.

Evidence to Collect​

  • The X-Gateway-Route-Source header value.
  • The asset-routing flag state.
  • Whether the response was native or compatibility-shaped.
  • A correlation identifier and timestamp.

Escalation​

Route gateway routing, the flag, and shadow behavior to the gateway owner. Route compatibility projection shape to the asset or backend team. Route monolith-side behavior to the monolith owner.

Source References​

  • microservices/src/gateway-api/Program.cs
  • microservices/src/asset-service/Api/AssetCompatEndpoints.cs
  • microservices/src/asset-service/Api/AssetEndpoints.cs

See Also​

Keywords​

gateway, routing flag, route source, compatibility shape, shadow route

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-17
  • Review cycle: Quarterly