Troubleshooting

Common issues with API References

Here are common issues and solutions for API References:

All of my OpenAPI pages are completely blank

Likely causes: Mintlify can’t find your OpenAPI document or it’s invalid.

To verify:

1. Run mintlify dev locally
2. Validate your OpenAPI document at apitools.dev/swagger-parser/online
3. Ensure you’re not using OpenAPI 2.0 (use editor.swagger.io to convert to OpenAPI 3)

One of my OpenAPI pages is completely blank

Common causes:

• Mismatched paths in metadata and OpenAPI document (check for exact matches, including slashes)
• Incorrect OpenAPI document filename reference

Example:

---
openapi: "GET /users/{id}/" # Path must exactly match OpenAPI document
---

Requests from the API Playground don't work

Solutions:

• If using custom domain: Configure reverse proxy to allow POST requests to /api/request
• Alternative: Set api.playground.disableProxy in mint.json to send requests directly (requires CORS configuration)