O'Hara Group

Troubleshooting CORS issues

Unless you are an experienced web developer (or perhaps even if you are), CORS can be difficult to understand and even harder to troubleshoot.

For many, using Open API Documentation for Confluence may be their first experience dealing with CORS, and our support team frequently help customers diagnose CORS related issues.

We have put together this CORS troubleshooting guide to assist.

About this guide

The following guide assumes Google Chrome.

However, all modern browsers (Chrome, Firefox, Edge, Safari) all come with similar tools, so you can perform these steps in any browser on any operating system (Windows, Mac, Linux).

Troubleshooting CORS in six steps

  1. Open the browser Developer Tools
  2. Go to the Network tab
  3. Filter the network requests
  4. Reload the Confluence page
  5. Check the OPTIONS response headers
  6. Check the GET response headers

Step 1: Open the browser Developer Tools 🔗

You can open the developer tools numerous ways, including:

  1. From the 3-dot menu in the top-right of the browser window, choose "More Tools" > "Developer Tools", or
  2. Press the `OPTION+CMD+I` hotkey combination, or
  3. Right-click anywhere on the Confluence page and choose "Inspect"

Step 2: Go to the Network tab 🔗

Across the top of the Developer Tools you will see different sections titled "Elements", "Console", "Sources", "Network" etc. (note the order of these sections may be different in your browser).

Click on the "Network" section:

Step 3: Filter the network requests 🔗

Near the top-left of the Network tab is a text input box with the word "Filter" in it:

Into this box, enter the name of your Open API JSON or YAML file.

For example, if the URL is https://petstore.swagger.io/v2/swagger.yaml , enter "swagger.yaml" into the filter.

Step 4: Reload the Confluence page 🔗

Now reload the Confluence page containing your Open API macro.

You should see one or more entries appear in the Network panel:

Step 5: Check the OPTIONS response headers 🔗

This step only applies if:

Your URL requires either a username and password...

...or a GitHub/GitLab access token:

If this doesn't apply to you, skip ahead to step 6.

In the case where your URL expects credentials such as a username/password or access token, the browser must perform what is called a "preflight" request.

You should see this as two separate requests in the Network tab:

  1. The initial request, which has a method of "GET + Preflight"
  2. Another request, which has a method of "OPTIONS"

Click on the OPTIONS request to show the response headers.

If the server that hosts your JSON/YAML file is configured correctly for CORS preflight, you should see the following response headers returned:

  1. access-control-allow-headers
  2. access-control-allow-methods
  3. access-control-allow-origin

Additionally, the status code returned for the preflight request should be 204:

If you don't see these access-control-allow-* headers returned, or the status code is not 204; then it likely means that the server that hosts your JSON/YAML is not correctly configured to support CORS.

Step 6: Check the GET response headers 🔗

Finally, after a successful preflight request (or no preflight was required), the browser will attempt to fetch your JSON/YAML file.

Click on the GET request to show the response headers.

If the server that hosts your JSON/YAML file is configured correctly for CORS, you should see the following response headers returned:

  1. access-control-allow-headers
  2. access-control-allow-methods
  3. access-control-allow-origin

Additionally, the status code returned for the GET request should be 200: