Support

We’re here to help you get the most out of Mintlify

Ask our docs

Ask our AI assistant that’s been trained on our documentation.

Dashboard widget

Send us a message from your dashboard. Select Support in your dashboard’s sidebar.

Email Us

If you can’t access your dashboard, email us at [e-mail].

Ask AI

Join our community and ask our AI assistant that’s been trained on our documentation.

YouTube

Watch tutorials and guides on our YouTube channel.

Frequently Asked Questions

GitHub app issues

The GitHub app can be temperamental and resetting the connection is a great way to solve issues.

1. Uninstall the Mintlify app through GitHub

   1. In GitHub, go to installations and select Configure next to the Mintlify app. Scroll down and select Uninstall.
   2. Go to Authorized GitHub Apps and select Revoke next to the Mintlify app.
2. Reinstall the Mintlify app

   1. In your Mintlify dashboard, go to Git Settings and install the GitHub app.
   2. Authorize your account in the My Profile section of your dashboard.

API page issues

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:

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 mint dev locally should reveal some of these issues.

To verify your OpenAPI document will pass validation:

1. Run mint openapi-check <openapiFilenameOrUrl> in your CLI.
2. Validate your OpenAPI spec with Swagger Editor.

Additionally, Mintlify does not support OpenAPI 2.0. If your document uses OpenAPI 2.0, you may encounter this issue. You can convert your document with Swagger Editor.

One of my OpenAPI pages is completely blank

This is usually caused by a misspelled openapi field in the page metadata. Make sure that 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:

get-user.mdx

---
openapi: "GET /users/{id}/"
---

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:

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

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.proxy setting in the docs.json. See the configurations for the API playground for more information. This will likely require you to configure CORS on your server, as these requests will now come directly from your users’ browsers.

Docs page won't load (error 404)

Check to see if you have /api in the URL. This is a reserved folder in production environments, which produces a 404 error.

Issues adding SVG to a card

We support a specific type of SVG, called JSX, and as such the image will need to be converted.

1. Use the SVGR converter to generate JSX compatible SVG code.
2. Copy the code inside the <svg/> tag.

3. Paste the code into your card. Make sure you only copy and paste the code inside the <svg/> tag.
4. You may need to decrease the height and width to make the image fit.

Bypassing the Onboarding Flow for GitLab

Since account creation is currently limited to GitHub, you’ll need to use a workaround to connect your GitLab repository. Follow these steps to bypass the standard GitHub-only onboarding flow:

1. Skip the first onboarding step

   When you first create your Mintlify account, you’ll see an onboarding flow that asks you to connect a GitHub repository. Skip this initial step.
2. Enter placeholder repository information

   In the second step of the onboarding process, enter the following placeholder information:

   • Organization: mintlify
   • Repository: starter

   This will allow you to proceed through the onboarding without connecting an actual GitHub repository.
3. Complete the onboarding

   Click through the remaining onboarding steps to reach your Mintlify dashboard.
4. Navigate to GitLab settings

   Once you’re in the dashboard, navigate to the GitLab settings page and connect your actual GitLab repository using the project ID and access token from the previous section.

We do our best to respond to all requests within 24 hours but delays may occur during busy times.