Edit

Share via

Troubleshooting 4xx and 5xx errors using RefString

  • Article

A guide to understand and use RefStrings for diagnosing and resolving issues with Azure Front Door.

Prerequisites

What is a RefString?

A RefString, also known as a Reference string, is a short string appended by Azure Front Door to the HTTP response headers of each request. It provides details on how the request was processed, including the point of presence (POP) and backend status.

RefStrings can help you troubleshoot and resolve issues with Azure Front Door, such as cache misses, routing errors, backend failures, and latency problems. You can identify the root cause and take appropriate actions to fix it by analyzing the RefStrings of the requests.

Note

If you encounter an error page from Microsoft services, it will already include a RefString for the request that generated the error page. In such cases, you can skip directly to the diagnostic step.

How to gather a RefString

To gather a RefString, you need to capture the HTTP response headers of the requests and look for the header named X-Azure-Ref. This header contains the RefString, encoded in Base64. You can use different methods to capture the HTTP response headers, depending on your preference and situation. Here is an example of how to obtain a RefString from the Microsoft Edge Browser:

  1. Open the browser's developer tools by pressing F12 or Ctrl+Shift+I.

  2. Go to the Network tab.

  3. Refresh the page or perform the action that triggers the request.

  4. Locate the specific request in the list and find the X-Azure-Ref header in the response headers section.

  5. Copy the value of the X-Azure-Ref header to use with the RefString troubleshooting tool in the Azure portal.

For more information, see Inspect network activity - Microsoft Edge Developer documentation.

Example of how to obtain a RefString from Microsoft Edge Browser:

Screenshot of RefString example in Microsoft Edge Browser.

How to use a RefString with some of our troubleshooting tools

Azure Front Door uses a RefString to manage 4xx and 5xx errors. The following are the steps to use the diagnostic tool with a RefString for tracking and diagnosing connectivity issues:

  1. Navigate to your Azure Front Door Profile.

  2. Select the Diagnose and solve problems menu.

    Screenshot showing the first step in diagnosing problems using a RefString.

  3. Scroll down and select Connectivity under the Common problems section.

    Screenshot showing the second step in diagnosing problems using a RefString.

  4. In the box What issue are you having? select Select a problem subtype and choose 4xx and 5xx errors on the drop down-menu, then select the Next.

    Screenshot showing the third step in diagnosing problems using a RefString.

  5. Enter your RefString in the box within the 4xx and 5xx errors section. You input the Restring given to you from your request under the Tracking Reference – RefString field.

    Screenshot showing the fourth step in diagnosing problems using a RefString.

  6. Finally, select Run Diagnostics to identify the cause of the issue, which explains the failure if it's a known problem.

    An example of a result displaying an issue:

    Screenshot showing an example of the diagnosis at work using a RefString.

    Note

    The diagnostic capabilities may require up to 15 minutes to deliver results. We ask for your patience that you allow the process to finish before taking further action.

Alternative option

If you choose not to use the diagnostic tool, you can include a RefString when submitting a support ticket. Additionally, you can enable the Access Logs feature to receive updates on RefString data directly in the Azure portal.

For more information on tracking references and access log parameters, see Monitor metrics and logs in Azure Front Door, which highlights specific fields in access logs that help identify various types of errors.

Next steps