Common errors

Most of the time, errors can be split into three categories:‌

Parsing errors

A parsing error can happen for three reasons:‌

  1. The parser met a new Markdown edge case that is not supported yet. In this situation, double-check the Markdown syntax and let us know if everything looks fine.

  2. The parser failed to parse the YAML front matter. To avoid this error, make sure that the YAML is properly formatted by using a YAML linter.

  3. The parser failed to read the configuration from the .gitbook.yaml file. Similar to the error above, check that the YAML is properly formatted thanks to a YAML linter. Additionally, make sure the configuration is valid by referring to the documentation on content configuration.


Regarding timeouts, they only happen when a file exceeds a certain size.‌

When facing a timeout, you might want to look for ways to split your large files into separate ones. With that being said, we are constantly working on improving performance so timeouts are very rare.

🧙♂ Tips: The overall size of the repository doesn't matter since each file is parsed separately.

🚧 API rate limiting

Since GitBook uses GitHub's API to perform actions on your repository using the GitBook OAuth app, it is subject to the GitHub rate limiting rules.

To prevent these errors, GitBook uses smart diffing logic to only import/export what was modified in your files when importing markdown from a GitHub commit and exporting your content on GitBook back to markdown. If the resulting number of files that were actually modified by a commit exceeds 2500, the import is currently automatically skipped to prevent affecting your rate limiting.

Even though we are doing our best to limit this effect, this kind of error can still happen, mainly in the following cases:

Initial sync setup

During an initial GitHub sync setup, it is possible to reach this limit since all the content needs to be initially imported to or exported from GitBook.

To prevent this to happen, you recommend setting up the sync as soon as possible, ideally when starting your documentation project.

When this is not possible, you can do the following to incrementally sync your content without hitting the rate limit.

Initial import

When importing from GitHub, ensure that you are only importing your documentation files using the .gitbook.yaml config file to scope your documentation to a single folder, and use a file.

The number of entries in the file can also be reduced during the initial import, then increased in another commit to finally include all your pages.

Initial export

When exporting from GitBook, try reducing the number of pages in your Table of Contents by publishing a new revision. Once the content has been exported to GitHub, rollback to the revision that includes all your content.

Using a single GitHub account

Since GitHub's API rate limiting is applied on a per-user basis, we recommend to use different GitHub accounts to sync your different spaces when possible.

Also make sure that you don't have any other 3rd party services (CI, Zapier, etc...) connected to the account used during the GitHub sync setup that could be performing operations on GitHub to reduce the risk.