If You Get mint.json Errors in Mintlify, Try Upgrading to docs.json
I’d like to share an error I encountered while using the documentation platform Mintlify and its solution.
Invalid mint.jsonTo build a documentation site with Mintlify, I wrote a configuration file mint.json while referring to the official documentation, and executed the mintlify dev command to preview it locally.
However, the following error message appeared and the build failed.
mintlify dev
🚨 Invalid mint.json:
#.navigation: Invalid type. Expected field to be of type 'array', received 'object'
error prebuild step failedReading the error message, it seems the issue is with the type of the navigation field in mint.json. It indicates “Expected array but received object”.
However, my configuration was in the format documented in the official documentation at the time, and I couldn’t immediately understand what the problem was.
Through investigation, I discovered that Mintlify’s configuration file had been upgraded from mint.json to docs.json.
While the old mint.json specification used an object format for navigation, the new docs.json changed it to an array format. This was the direct cause of the error.
The official documentation also contained detailed upgrade procedures from mint.json to docs.json.
docs.jsonFollowing the official upgrade guide, I migrated the configuration file from mint.json to docs.json.
npm i -g mintmint updatemint upgraderm mint.jsonAfter this fix, when I ran mint dev, the local server started successfully and I was able to preview the site.
For reference, I’ll share the Pull Requests of the actual docs.json upgrade work I performed. If you want to check specific file differences, please refer to these.
If you face the same error, first check whether your configuration file complies with the latest docs.json specification.
That’s all from the Gemba.