Running Mintlify?

Mintlify docs build red or playground broken? We unstick it.

Mintlify looks like a clean swap for a tired docs site until the docs.json schema tightens between releases, an OpenAPI playground starts returning 404s, or an MDX page fails validation with an error only the build log mentions. We walk through the config, fix the broken references, and leave you with a docs site that builds green from a push.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

mintlify-build.log

red

What it is

Mintlify at a glance

Mintlify is a documentation platform aimed at developer teams, rebuilt from the ground up around MDX, a JSON configuration file and a hosted preview that updates as you push. It handles API reference from an OpenAPI spec, SDK samples, a global search, AI-assisted answers over your docs, custom components and multi-version documentation.

The company was founded in 2021 and is based in San Francisco. Pricing starts with a free tier for small open-source projects and climbs through startup and enterprise tiers for larger teams. The product has moved fast, with the configuration file renaming from mint.json to docs.json and the schema tightening across minor releases.

Type
Hosted documentation platform for developer products
First released
2021
License
Proprietary SaaS, tiered pricing with a free open-source tier
Maintained by
Mintlify, Inc.
Typically used for
API reference, developer guides, SDK docs, OpenAPI playground, AI search over documentation

The honest version

Mintlify pros and cons

No technology is all upside. This is where Mintlify earns its place and where it tends to cause trouble.

Where Mintlify is strong

  • Great out of the box lookThe default theme produces a polished docs site without fighting a CSS system, which saves a week most teams would otherwise spend on branding.
  • OpenAPI playground is first classPoint it at a spec and you get interactive endpoints, code samples in several languages and auth helpers without extra work.
  • AI search is genuinely usefulThe embedded answer engine is good enough to answer common support questions from your own docs, which cuts the ticket load noticeably.
  • Component library covers the common needsCallouts, cards, accordions, tabs and code groups are built in, so an MDX writer is not constantly stepping outside the system.
  • Git-based workflowDocs live in your repository and build on push. There is no separate editor to keep in sync.

Where Mintlify bites

  • Config schema has changed more than oncemint.json became docs.json, properties renamed, structures tightened. Teams who followed a tutorial from last year run into surprise validation errors on upgrade.
  • OpenAPI playground is unforgivingSpec errors that other tools render gracefully fail the whole playground. Operation IDs, mismatched response codes and un-resolved $refs all break interaction.
  • MDX errors are hard to locateA mismatched closing tag or a duplicate frontmatter key shows up in the build log with limited line context. Larger docs sites spend time triangulating.
  • Pricing is per seat and per projectA small team maintaining several products quickly outgrows the cheaper tiers, and the jump to enterprise is a conversation rather than a published number.
  • Customization has limitsBeyond theme colors, logo and components, deeper design or custom layouts need escape hatches that are not always supported cleanly across releases.
  • Build times climb with large navsA docs site with thousands of pages and deeply nested navigation can push build times into minutes, and the CLI preview loop slows accordingly.

Sound familiar?

Common Mintlify problems we fix

The Mintlify problems that bring people to us, and what you have once each one is fixed.

docs.json: unknown property 'tabs'

Config file no longer validates

A property moved, got renamed or stopped being accepted between releases. The site builds locally on an old CLI and fails on the hosted preview, or the other way around.

Config clean against the current schema

OpenAPI: operationId 'getUser' not found

Playground endpoints return 404

An operationId in the nav does not match the spec, the base URL is pointing at staging, or a $ref points at a schema that was removed. The playground looks fine until someone clicks Try it.

Playground that returns real responses

Unable to parse frontmatter: duplicate 'title' key

MDX pages fail to render

A frontmatter block with a duplicate key, a YAML that is not quite valid YAML, or a page with an image path that has a space in it. Build fails late and the preview falls back.

MDX that validates on every push

Component <AccordionGroup> missing closing tag

Component typos break the page

An unclosed tag or a mis-nested component leaves the renderer lost. The build log points at line 142 but the real error is twenty lines earlier.

Components balanced and linted

GitHub integration: webhook secret rotated

Pushes do not trigger a rebuild

A webhook secret was rotated during a security review, the Mintlify integration was never updated, and docs have been serving the old build for days without anyone noticing.

Deploy webhook healthy

AI search: embeddings rebuild queued

AI search answers from stale content

A recent push hasn't been re-indexed yet. The answer references a method that no longer exists, which is worse than a plain miss.

Index refresh aligned with releases

Playground base URL mismatch

Try-it-live calls the wrong environment

The playground is pointed at the production URL from a spec meant for staging, so test calls hit real data and get rejected, or worse, succeed.

Playground wired to the right environment

What we do

Mintlify help, from setup to upkeep

Call us for one broken docs build, or let us own the Mintlify site alongside your API team.

Rescue
Builds red after a config bump, playgrounds returning 404s, or an MDX page that nobody can fix. We stabilise the site first.
OpenAPI playground
Spec cleaned, operation IDs normalised, auth helpers set per environment and example payloads that produce useful responses on the first click.
Information architecture
Navigation, tabs, versioned docs and redirects laid out so readers find the right page, with analytics to catch the 404s that pile up after a rename.
AI search and support
Tuning the embedded search and AI answers so they pull from the right sections, with feedback loops into your support team's triage.
Managed Tech
Ongoing watch on build health, config schema upgrades, broken link reports, playground environments and a person to call when the docs go dark before a product launch.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Mintlify alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Mintlify questions

Something else? Call+1 737 727 7327

Why does our Mintlify docs build keep failing after an upgrade?

The configuration schema has changed more than once, including the file name from mint.json to docs.json, and several property names along with it. A build that was green on an older CLI fails on the hosted preview because the hosted version validates against a newer schema. Pinning both sides to a known version and migrating properties in a controlled pass is the lasting answer.

How do we fix a broken OpenAPI playground?

Start with the spec, not Mintlify. Validate the OpenAPI with a tool like Spectral, resolve every $ref, check that every operationId referenced in the nav exists, and confirm the servers block points at the environment you want the Try it button to hit. Once the spec is clean the playground usually comes back on its own.

Should we use Mintlify, GitBook or ReadMe?

Each solves a different shape of docs. Mintlify is MDX-first, great when docs live alongside code and your team is comfortable with components. GitBook is strong for mixed editorial and developer content. ReadMe leans into API reference and metrics. We give an honest view based on who writes your docs and how often, rather than the product we last deployed.

Why is our AI search returning stale answers?

The embeddings index rebuilds asynchronously after a push, so for a short window the AI answer can reference pages that no longer exist. For teams that ship docs with product releases we add a rebuild trigger on the deploy webhook and verify the index before the release note goes out.

How do we migrate from Docusaurus or MkDocs to Mintlify?

Content moves cleanly enough, since both source formats are close to MDX, but navigation and components need a rebuild in the Mintlify shape. We map the information architecture first, convert the components in batches, and run both sites in parallel until the Mintlify version is a strict superset of the old one before cutting DNS.

How much does Mintlify help cost?

Estimates are at no charge. Describe the docs size, the build failures and your API surface, and we return a price before any work begins.

Free estimate

Mintlify docs stuck?

Share the repo, the CLI version and the build log. A real person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.