Common errors

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

  • Parsing errors

  • Timeouts

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.