> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-han-update-changelogs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues with API References

API pages are complicated. As a result, there are a lot of things that can go wrong.
Here's a list of common issues we've seen customers run into:

<AccordionGroup>
  <Accordion title="All of my OpenAPI pages are completely blank">
    In this scenario, it's likely that either Mintlify cannot find your OpenAPI document,
    or your OpenAPI document is invalid.

    Running `mintlify dev` locally should reveal some of these issues.

    To verify your OpenAPI document will pass validation:

    1. Visit [this validator](https://apitools.dev/swagger-parser/online/)
    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](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3):

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify-han-update-changelogs/images/convert-oas-3.png" />
    </Frame>
  </Accordion>

  <Accordion title="One of my OpenAPI pages is completely blank">
    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 exactly.

    Here's an example of how things might go wrong:

    ```md get-user.mdx
    ---
    openapi: "GET /users/{id}/"
    ---
    ```

    ```yaml openapi.yaml
    paths:
      "/users/{id}":
        get: ...
    ```

    Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI
    document does not.

    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:

    ```md api-reference/v1/users/get-user.mdx
    ---
    openapi: "v1 GET /users/{id}"
    ---
    ```
  </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
    `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET`
    requests, then all of these requests will fail. To fix this, configure your reverse proxy to
    allow `POST` requests to the `/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.disableProxy`
    setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will
    likely require you to configure CORS on your server, as these requests will now come directly
    from your users' browsers.
  </Accordion>
</AccordionGroup>