Update from support feedback: OpenAPI URL fetch failures during build

.vale/styles/config/vocabularies/Mintlify/accept.txt

@@ -9,7 +9,7 @@ AI
 (?i)airgap
 AKS
 allOf
-allowlists?
+allowlist(s|ed|ing)?
 AllViewerExceptHostHeader
 Anthropic
 anyOf

api-playground/troubleshooting.mdx

@@ -68,6 +68,22 @@ If your API pages aren't displaying correctly, check these common configuration
     ---
     ```
   </Accordion>
+  <Accordion title="My build fails with &quot;Failed to fetch OpenAPI file for anchor or tab&quot;">
+    This error means Mintlify could not download the OpenAPI document at the URL in your `docs.json` `openapi` field during the build. Common causes include:
+
+    - The host is unreachable or resolves only from a private network.
+    - The URL requires authentication (a token, session cookie, or IP allowlist).
+    - The certificate is invalid or the domain has a DNS issue.
+    - The origin returned a transient 5xx or timed out.
+    - The spec was being republished at the moment the build ran, so the URL served a partial or empty response.
+
+    Builds fetch the URL from the public internet without credentials, so confirm that the document downloads with `curl` from a machine outside your network. To fix the error, switch to one of these patterns:
+
+    - **Commit the spec into your docs repo.** This is the recommended pattern when the source URL is behind auth. Point the `openapi` field at the repo-relative path (for example, `"openapi": "openapi.json"`) and update the file in the same commit that changes your API.
+    - **Serve the spec from a stable public HTTPS URL.** Host it on a CDN or object storage bucket that does not require auth, has a valid TLS certificate, and returns the full document on every request.
+
+    For a full diagnostic walkthrough, including intermittent failures caused by CI publishing the spec after triggering the build, see [Build fails with "Failed to fetch OpenAPI file for anchor or tab"](/help-center/openapi-url-fetch-fails-during-build).
+  </Accordion>
   <Accordion title="Requests from the API Playground don't work">
     If you have a custom domain configured, this could be an issue with your reverse proxy. By
     default, requests made via the API Playground start with a `POST` request to the

docs.json

@@ -451,6 +451,19 @@
               }
             ]
           },
+          {
+            "tab": "Help center",
+            "hidden": true,
+            "searchable": true,
+            "groups": [
+              {
+                "group": "Help center",
+                "pages": [
+                  "help-center/openapi-url-fetch-fails-during-build"
+                ]
+              }
+            ]
+          },
           {
             "tab": "Learn",
             "menu": [

help-center/openapi-url-fetch-fails-during-build.mdx

@@ -0,0 +1,45 @@
+---
+title: "Build fails with \"Failed to fetch OpenAPI file for anchor or tab\""
+description: "Diagnose why a Mintlify build cannot download a hosted OpenAPI document, including private hosts, authenticated URLs, TLS and DNS problems, and CI race conditions."
+keywords: ["Failed to fetch OpenAPI file", "OpenAPI build error", "openapi URL", "spec fetch", "build failure", "CI race condition"]
+---
+
+When your `docs.json` `openapi` field points at a URL instead of a file in your repository, Mintlify downloads that document during every build. If the download fails, the build fails with `Failed to fetch OpenAPI file for anchor or tab`. For an overview of the common causes and the recommended fix, see [API playground troubleshooting](/api-playground/troubleshooting).
+
+This page covers how to narrow down the cause when the fix isn't obvious.
+
+## Reproduce the fetch outside Mintlify
+
+Mintlify builds run from the public internet with no access to your network or credentials. Run these commands from a machine that is not on your VPN or corporate network:
+
+```bash
+curl -IL "https://example.com/openapi.json"
+curl -o openapi.json "https://example.com/openapi.json"
+```
+
+Check the response for these signals:
+
+- A connection timeout or DNS failure means the host isn't publicly resolvable.
+- A `401` or `403` means the URL requires authentication. Build fetches are unauthenticated and cannot send a token, cookie, or come from an allowlisted IP.
+- A certificate error means the TLS chain is incomplete. Browsers often accept a chain that automated clients reject, so a URL that loads for you can still fail during a build.
+- A `200` with a truncated or empty body means the origin served a partial response.
+
+Then validate the document you downloaded:
+
+```bash
+mint validate
+```
+
+If validation fails, the problem is the document itself rather than the fetch. See [OpenAPI setup](/api-playground/openapi-setup).
+
+## Rule out a CI race condition
+
+If your pipeline generates the spec and then calls the [Trigger deployment](/api/update/trigger) endpoint, an intermittent failure usually means the deployment starts before the new spec finishes publishing. The build then fetches a stale document, a partial document, or nothing at all.
+
+Sequence the pipeline so the spec is fully published and readable at its public URL before you trigger the deployment. Confirm the upload completed rather than assuming it did. Object storage and CDN uploads often return before the object is served consistently.
+
+This failure mode is intermittent by nature. A build that succeeds on retry without any change to the spec is a strong signal that you're hitting it.
+
+## When the URL can't be public
+
+If you cannot serve the spec from an unauthenticated public URL, commit it into your documentation repository and point the `openapi` field at the repo-relative path. Update the file in the same commit that changes your API so the two stay in sync. See [`mint validate`](/cli/commands#mint-validate) to check the document before you commit it.