Fix a static file that returns 404 on your docs site

Mintlify serves static files from your documentation repository at the path that matches their location in the repo. If a file like data/prices.json returns 404 when you request https://docs.example.com/data/prices.json, work through the causes below. For an overview of how static file serving works and the list of supported file types, see Files.

​

Confirm the URL matches the repo path

The URL path mirrors the file’s location in your repo. A file committed to the root of the repo as prices.json is served at https://docs.example.com/prices.json. A file at data/prices.json is served at https://docs.example.com/data/prices.json. Common mistakes:

• Case mismatch. Prices.json and prices.json are different URLs.
• The file is only in a feature branch. Only files committed to the branch Mintlify builds are served.
• A typo in the extension. Mintlify serves the file at the exact filename it has in the repo.

Confirm the file exists on the deployed branch by opening it directly in your Git provider’s web UI.

​

Check that the file type is supported

Mintlify only serves the file types listed in Supported file types. Some types, like .pdf, .txt, .xml, .csv, and .zip, are only served on Enterprise plans. A file with an unsupported extension returns 404 even when it exists in the repo.

​

Check the file size

Files must be less than 20 MB. Larger files are not served and must be hosted on an external CDN or object store.

​

Rule out authentication

Static file serving is not supported for documentation sites with authentication enabled. Direct URLs to files return 404 on authenticated sites even when the file exists and the user is signed in. Host the file on an external service if your site requires authentication.

​

Rule out .mintignore and other exclusions

Check whether the file matches a pattern in .mintignore. Mintlify does not publish files that match .mintignore patterns, so they are not available at their URL. See Exclude files from publishing. Mintlify also automatically ignores directories like node_modules, build, dist, and .git. A file inside one of those directories is not served. Move the file to a directory that is not auto-ignored, like assets/ or data/. See the full auto-ignored list in Default ignored patterns.

​

Redeploy after adding the file

Mintlify builds your documentation when you push to your deploy branch. A newly added file is only available after the next successful build. Open your dashboard’s deployment history and confirm the commit that added the file was built successfully before you retest the URL.