Skip to main content
If your API pages aren’t displaying correctly, check these common configuration issues.
In this scenario, it’s likely that either Mintlify cannot find your OpenAPI document, or your OpenAPI document is invalid.Running mint dev locally should reveal some of these issues.To verify your OpenAPI document passes validation:
  1. Visit this validator.
  2. Switch to the Validate text tab.
  3. Paste in your OpenAPI document.
  4. Click Validate it!
If the text box that appears below has a green border, your document has passed validation. This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document passes validation here, there’s a great chance the problem is elsewhere.Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, you could encounter this issue. You can convert your document at editor.swagger.io (under Edit > Convert to OpenAPI 3):
Screenshot of the Swagger Editor with the Edit menu expanded and the "Convert to OpenAPI 3" menu item highlighted.
This is usually caused by a misspelled openapi field in the page metadata. Make sure the HTTP method and path match the HTTP method and path in the OpenAPI document.
Mintlify automatically resolves trailing slash differences between your openapi reference and the OpenAPI specification. For example, GET /users/{id}/ matches a specification path of /users/{id}.
Here’s an example of how things might go wrong:
get-user.mdx
openapi.yaml
Notice that the path in the openapi field says /user/{id} (singular), whereas the path in the OpenAPI document is /users/{id} (plural).Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document in the openapi field, ensure the filename is correct. For example, if you have two OpenAPI documents openapi/v1.json and openapi/v2.json, your metadata might look like this:
api-reference/v1/users/get-user.mdx
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 /_mintlify/api/request path on the docs site. If you configure your reverse proxy to only allow GET requests, then all of these requests fail. To fix this, configure your reverse proxy to allow POST requests to the /_mintlify/api/request path.Alternatively, if your reverse proxy prevents you from accepting POST requests, you can configure Mintlify to send requests directly to your backend with the api.playground.proxy setting in the docs.json. See the settings documentation for details. When using this configuration, you must configure CORS on your server since requests come directly from users’ browsers rather than through your proxy.
A CORS error occurs when your browser blocks a cross-origin request because the response is missing the required headers. You can identify a CORS error in your browser’s developer console: look for messages like Access-Control-Allow-Origin missing or blocked by CORS policy.CORS errors only affect requests that go directly from the user’s browser to your API. By default, Mintlify proxies API Playground requests through /_mintlify/api/request, so most sites don’t encounter CORS issues. You typically see CORS errors when:
  • You’ve set api.playground.proxy to false in your docs.json, so requests bypass the Mintlify proxy.
  • You’ve configured a custom api.playground.proxy URL that points directly to your backend.
To fix CORS errors, configure your API server to return the following response headers for requests from your docs site’s origin:
  • Access-Control-Allow-Origin: Your docs site’s origin (for example, https://docs.your-site.com) or * for public APIs.
  • Access-Control-Allow-Methods: The HTTP methods your API supports (for example, GET, POST, PUT, DELETE, OPTIONS).
  • Access-Control-Allow-Headers: The headers your requests send (for example, Content-Type, Authorization).
Your server must also handle OPTIONS preflight requests. If you can’t modify your API server, remove the api.playground.proxy setting so requests route through the Mintlify proxy again.
If you are using an OpenAPI navigation configuration, but the pages aren’t generating, check these common issues:
  1. Missing default OpenAPI spec: Ensure you have an openapi field set for the navigation element:
  1. OpenAPI spec inheritance: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
  2. Validation issues: Use mint validate to verify your OpenAPI document is valid.
  1. Hidden operations: Operations marked with x-hidden: true in your OpenAPI spec won’t appear in auto-generated navigation.
  2. Invalid operations: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
  3. Manual vs automatic inclusion: If you reference any endpoints from an OpenAPI spec, only the explicitly referenced operations appear in navigation. No other pages are automatically added. This includes operations that are referenced in child navigation elements.
When combining OpenAPI operations with regular documentation pages in navigation:
  1. File conflicts: You cannot have both an MDX file and a navigation entry for the same operation. For example, if you have get-users.mdx, do not also include "GET /users" in your navigation. If you need to have a file that shares a name with an operation, use the x-mint extension for the endpoint to have the href point to a different location.
  2. Path resolution: Navigation entries that don’t match OpenAPI operations are treated as file paths. Ensure your MDX files exist at the expected locations.
  3. Case sensitivity: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.