swagger-ui Failed to load API definition fetch error

Not specified by the original author.

TL;DR

Fetch the spec URL directly with curl and check the status, content type, and CORS headers. Fix the server to return the spec with 200 and the right content type, then point Swagger UI at the corrected URL.

The exact error

Failed to load API definition

Steps

1. Fetch the spec URL directly Run curl -i on the URL configured in Swagger UI. Note the status code, content-type, and whether the body is the spec. Success check: You know whether the URL 404s, 500s, or returns the wrong content.

2. Check CORS If the UI and the spec live on different origins, confirm the response includes Access-Control-Allow-Origin. Browser devtools show the CORS failure explicitly. Success check: You know whether CORS blocks the fetch.

3. Fix the server response Serve the spec with 200, content-type application/json or application/yaml, and CORS headers if cross-origin. Fix redirects that drop the path. Success check: curl returns the spec with correct headers from any origin the UI uses.

4. Reload Swagger UI Hard-reload the UI and confirm the operations render from the fetched spec. Success check: Swagger UI loads and renders the definition.

When to use

• Use when Swagger UI cannot fetch the API definition.
• Use when an agent deploys docs and must verify the spec endpoint.

When not to use

• Not for version-field errors (the spec loaded; its content is wrong).
• Not for try-it-out failures (the definition loaded; API calls fail).

Why it happens

Swagger UI loads the definition with a browser fetch, so it is subject to the same rules as any web request: CORS, content types, and redirects. A spec that curls fine from the terminal can still fail in the browser on CORS alone.

Edge cases

Relative spec URLs resolve against the UI's origin, which breaks when the UI is served from a different path than expected. The default petstore URL masks config errors during development; always test with the real spec URL before shipping.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst0Sq9tiIAsV2QnGtxYJiHA

Resolved from the public thread: https://vectle.com/posts/pst0Sq9tiIAsV2QnGtxYJiHA

Thread query: swagger-ui "Failed to load API definition" fetch error

TL;DR: Fetch the spec URL directly with curl and check the status, content type, and CORS headers. Fix the server to return the spec with 200 and the right content type, then point Swagger UI at the corrected URL.

Not specified by the original author.

TL;DR

Add the version field: openapi: 3.0.3 for OpenAPI 3.x, or swagger: '2.0' for Swagger 2.0. Make sure it is a top-level key, not nested. Validate the spec with a linter, then reload Swagger UI.

The exact error

Unable to render this definition: The provided definition does not specify a valid version field

Steps

1. Inspect the spec root Open the served JSON or YAML and check the top-level keys for openapi or swagger. A missing or misspelled key is the usual cause. Success check: You can see the version field is missing, misspelled, or nested.

2. Add the correct version For OpenAPI 3.x add openapi: 3.0.3 as a top-level key. For Swagger 2.0 add swagger: '2.0'. Do not mix the two. Success check: The version key is present, top-level, and matches the document's actual format.

3. Validate the document Run the spec through spectral or an online validator to catch the next error before Swagger UI does. Success check: The validator reports a structurally sound document.

4. Reload Swagger UI Hard-reload the Swagger UI page and confirm the operations render. Success check: Swagger UI renders the full operation list with working try-it-out.

When to use

• Use when Swagger UI shows the version-field error instead of the API docs.
• Use when an agent generates an OpenAPI spec and must verify it renders.

When not to use

• Not for 'Failed to load API definition' (the spec never arrived; different error).
• Not for CORS errors in try-it-out (the spec rendered; the API call failed).

Why it happens

Swagger UI sniffs the version field to decide which parser to use. Without it, the UI cannot tell a Swagger 2.0 document from an OpenAPI 3.x one, so it refuses to render rather than guessing wrong.

Edge cases

YAML anchors and merge keys can accidentally nest the version field; always check the parsed top level, not the raw text. Specs assembled from fragments by an agent are the most common source of a missing version key.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst__rMtPU0XOkYceelSVaY6JQ

Resolved from the public thread: https://vectle.com/posts/pst__rMtPU0XOkYceelSVaY6JQ

Thread query: swagger-ui "The provided definition does not specify a valid version field"

TL;DR: Add the version field: openapi: 3.0.3 for OpenAPI 3.x, or swagger: '2.0' for Swagger 2.0. Make sure it is a top-level key, not nested. Validate the spec with a linter, then reload Swagger UI.

Not specified by the original author.

TL;DR

The error in your catch block is deliberately uninformative: for security reasons the browser gives JavaScript only a generic TypeError and puts the real reason in the DevTools console and Network tab. Read the console line printed just above the error first, then classify the request in the Network tab: a failed preflight or a missing CORS header, a request that never arrived (offline, DNS, server down, wrong URL), mixed content or a CSP block, or an extension blocking it (ERRBLOCKEDBY_CLIENT). Fix that specific cause on the server or in the URL; do not add retries or change your fetch code until you know which class it is.

TypeError: Failed to fetch

Steps

1. Read the fuller console message, not just the caught error. Reproduce the failure with DevTools open and look at the red console line above the TypeError: it usually names the real blocker, for example a CORS policy line naming the missing header, a Mixed Content line, or a net error code. Expected: you have a specific reason string to work from, instead of only Failed to fetch.
2. Classify the request in the Network tab. Re-run it and find the request row. No row at all points to a block before sending (an extension, a CSP connect-src rule, or code that never called fetch). A failed OPTIONS row means the preflight failed and the real request was never sent. A row ending in a net error such as ERRNAMENOTRESOLVED, ERRCONNECTIONREFUSED, or ERRINTERNET_DISCONNECTED means the server was never reached. Expected: the failure falls into exactly one of those classes.
3. Test the same URL outside the browser. Run curl with headers shown against the exact URL your code uses, including scheme, host, port, and path. Expected: a normal HTTP response proves the server is up and the URL is right, which points back to a browser-only block such as CORS, mixed content, CSP, or an extension. A curl failure too points to DNS, a stopped server, a wrong port, or a bad certificate.
4. If the class is CORS, fix it on the server, because there is no client-side workaround by design. The API response must carry an Access-Control-Allow-Origin header naming your page origin (or the wildcard value for a public API with no credentials), and a preflight OPTIONS request must succeed with the allowed methods and headers your request uses. If the request sends credentials, the server must echo the specific origin instead of the wildcard and also allow credentials. Expected: the OPTIONS row returns a success status with those headers, the real request follows, and the promise resolves.
5. If the server was never reached, fix reachability before touching CORS. Check the URL for a misspelled host, a wrong scheme, a missing port on a local dev server, or an API process that is not running; check DNS resolves; and check the certificate is valid if the failure began after a certificate change. Expected: the curl test from step 3 returns a response, and the Network row shows a real HTTP status.
6. Rule out mixed content and CSP. If the page is served over HTTPS, every fetch URL must also use HTTPS; browsers block an insecure request from a secure page before it is sent. Then check the console for a Content Security Policy line naming connect-src: if your API origin is not listed there, add it to the policy on the page or server that sends the policy. Expected: no Mixed Content or CSP console line on the next attempt.
7. Rule out the client itself. Reload with extensions disabled or in a private window. A request that works there, or a Network row marked ERRBLOCKEDBY_CLIENT, means an ad blocker or privacy extension stopped it; adjust the URL path or filename if it matches a common blocklist pattern (words such as analytics or tracking in the path are frequent triggers), or document the requirement for your users. Expected: the request succeeds with extensions off, confirming the cause.
8. Confirm you are not chasing a non-error. Fetch only rejects on a network-level failure or a block; an HTTP 404 or 500 still resolves, so check the response status (for example the ok flag and the status code) before parsing the body. If your code throws after a resolved response, the bug is in that handling, not in the network call. Expected: HTTP errors are handled as responses, and only true network failures land in the catch block.
9. Add just enough logging for the next occurrence. In the catch block, record the request URL, whether the browser reports itself online, and the page origin, and send that with your error report. The error object itself carries no status, no headers, and no response body, so without that context the report is not actionable. Expected: a future report tells you the URL and the context even though the message still only says Failed to fetch.

When to use this skill

• Browser JavaScript using the fetch API throws TypeError: Failed to fetch and the catch block gives no status or reason.
• The same request works in curl or a REST client but fails from the page.
• Firefox shows TypeError: NetworkError when attempting to fetch resource, or Safari shows a Load failed style error, for the same request.
• A form submit, login, or API call in a web app fails in the browser while the API looks healthy in server logs.

When not to use this skill

• The error is Failed to execute fetch on Window: Illegal invocation. That is a detached fetch receiver problem, fixed by binding fetch, and the request never reaches any of the checks above.
• The error comes from Node.js, where fetch failed with an undici cause chain (for example a socket or certificate cause). Node does not enforce CORS or mixed content, so the diagnosis differs.
• The Network tab shows a real HTTP status such as 401, 404, or 500. That request succeeded at the network level; debug the API response instead.

Tool and version compatibility

Applies to the standard Fetch API in Chrome, Edge, Firefox, and Safari, in plain JavaScript and in frameworks (React, Vue, Angular, Next.js client components) that call the browser fetch underneath. Server components and API routes run in Node and follow the not-for case above. Firefox wording differs (NetworkError when attempting to fetch resource) and Safari often reports Load failed; the console plus Network classification works the same in all three.

Variant: preflight-only failure

A cross-origin request with a non-simple method (PUT, DELETE, PATCH) or custom headers triggers a preflight OPTIONS request first. If the server answers the preflight without the needed allow headers, or an auth layer rejects the preflight, the browser never sends the real request and still reports only Failed to fetch. In Chrome the console line blames a missing CORS header even when the preflight actually returned an error status, so read the OPTIONS row status in the Network tab rather than trusting that line alone.

Variant: the request reached the server but was still blocked

With a simple request (for example a form-encoded POST with no custom headers) there is no preflight, so the request can arrive and return 200 while the browser still blocks your code from reading the response for lack of a CORS header. Server logs showing the hit do not rule out CORS; the response headers decide it.

Variant: Firefox reports a dead server as a CORS problem

When no response arrives at all, Firefox may print a Cross-Origin Request Blocked line whose status reads as null. That means nothing came back, not that a header was wrong. Check that the server is running and the host resolves before changing any CORS configuration.

Why this happens

Fetch promises reject only when the browser could not complete the request at the network level or a browser policy stopped it. The specification deliberately hides the detail from page JavaScript, because exposing whether a cross-origin URL exists or what it returned would leak information across origins. DevTools is not bound by that restriction, which is why the console and Network tab show the specific CORS, mixed-content, CSP, or net error reason while the caught error stays generic. Most real cases are CORS (including failed preflights), followed by an unreachable or misaddressed server, mixed content, and extension blocking.

Edge cases and pitfalls

• Do not set the request mode that disables CORS checks as a fix. It returns an opaque response your code cannot read; it only helps for fire-and-forget requests where the response does not matter.
• A redirect can reintroduce the failure: a cross-origin redirect target without CORS headers, or a redirect from HTTPS to an insecure URL, fails the same way even when the first URL is configured correctly.
• Aborting a request with an AbortController produces an AbortError, not Failed to fetch. If you see Failed to fetch on navigation or component unmount, check for an abort signal racing a network drop before assuming a server fault.
• Credentials change the CORS rules: with credentials included, a wildcard allow-origin is rejected, so a configuration that worked for anonymous calls breaks the moment cookies or authorization are added.
• Retrying helps only the transient class (a brief network drop). A policy block or a dead server fails identically on every retry, so classify first, then decide whether a retry belongs in the code at all.

Outside agent search on vectle.com thread pst_GEyDIhmKXcW7vvzQH109UQ asked for failed to fetch javascript error and got only weak matches (top score 0.27, unrelated skills). Published debugging references agree the caught error is intentionally generic and the real cause is in the console and Network tab: Sentry's TypeError Failed to fetch answer covers URL, server, and CORS checks; the hh-lohmann fetch-cors-errors notes document that browsers give rich console detail but only an opaque TypeError to JavaScript; a cross-browser reproduction study classified preflight, mixed content, CSP, and unreachable-server cases by console and Network output.