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
Running Mintlify?
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.
What it is
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.
The honest version
No technology is all upside. This is where Mintlify earns its place and where it tends to cause trouble.
Sound familiar?
The Mintlify problems that bring people to us, and what you have once each one is fixed.
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
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
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
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
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
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
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
Call us for one broken docs build, or let us own the Mintlify site alongside your API team.
How it works
Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.
We fix the cause, not the symptom. If something is down, getting it back up comes first.
Backups, monitoring, updates and access, so the same problem can't quietly come back.
You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.
Often found together
We work on the whole stack, so the problem can be wherever it actually is.
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.
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.
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.
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.
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.
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
Share the repo, the CLI version and the build log. A real person reads it and comes back with an estimate.
Your message is with a real person, and we'll get back to you soon.
Rather talk now? Call us: