Fixing “Failed to fetch” and CORS errors in Swagger UI on Confluence

Updated October 2026 · 5 minute read

You add an OpenAPI macro to a Confluence Cloud page, point it at your specification, and get one of these:

Failed to fetch.
Possible Reasons:
  - CORS
  - Network Failure
  - URL scheme must be "http" or "https" for CORS request.
Fetch error: Failed to fetch https://api.example.com/openapi.json
The URL origin does not match the page.

Both come from the same browser security rule: cross-origin resource sharing (CORS).

Why it happens

Marketplace apps render inside an iframe served from Atlassian's app CDN, not from your Confluence site and not from your API. When code in that iframe requests your spec or your API, the browser only lets it read the response if the server replies with an Access-Control-Allow-Origin header that allows the iframe's origin.

Two different requests can be affected:

  • Loading the spec (the macro shows an error instead of documentation).
  • Try it out (the docs load, but every test request fails).

Fix 1: Allow the app's origin on the server

If you control the server, add a CORS header for the app's origin. Your app vendor's documentation should tell you the exact origin; Forge apps run on a per-app subdomain of cdn.prod.atlassian-dev.net. This works, but it means changing production infrastructure for documentation, and each app (or app update) can change the origin.

Fix 2: Host the spec somewhere that sends CORS headers

For the spec itself, you can publish it to a host that sends Access-Control-Allow-Origin: * – for example GitHub raw URLs, or a static site where you control headers. That fixes loading, not Try it out.

Fix 3: Paste or attach the spec

Pasting the YAML into the macro or attaching the file to the page avoids the first request entirely. The downside is that the page no longer updates when the API changes.

Fix 4: Use an app that fetches and relays server-side

Some apps fetch the spec on their backend and can relay Try it out requests from the backend too, so the browser never makes a cross-origin call. This is the only option that fixes both problems without touching your servers. If you go this route, check that the relay only contacts the servers declared in your specification and that an admin can turn it off.

API Docket works this way: specs are fetched by its Forge backend, and Try it out requests are relayed only to the servers listed in your spec, with cookies stripped and redirects not followed. Admins can disable the relay for the whole site, in which case requests go directly from the reader's browser.

Still failing?

  • Check that the spec URL uses https:// – browsers block plain HTTP from secure pages.
  • Relative server URLs like /api/v3 are resolved against the page, not your API. Use absolute URLs in your servers list.
  • APIs only reachable on your corporate network can't be called from a cloud backend; use direct browser requests for those, with CORS configured.