diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index f576aa6e03..e786645207 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -202,6 +202,17 @@ ruby-lsp
 Is there any extra information given from booting the server manually? Or does it only fail when booting through the
 extension?
 
+## Indexing ##
+
+When Ruby LSP starts, it attempts to index your code as well as your dependencies as described in [Configuring code indexing](README.md#Configuring-code-indexing).
+
+In rare cases, Ruby LSP will encounter an error which prevents parsing from completing, meaning Ruby LSP cannot start.
+
+To diagnose the particular file(s) causing a problem, run `ruby-lsp --doctor`. Please log an issue so that we we can address it. If the code is not open source then you can try write a minimal reproduction.
+
+In the meantime, you can [configure Ruby LSP to ignore a particular gem or file for indexing]([README.md#Configuring-code-indexing]).
+
+
 ## After troubleshooting
 
 If after troubleshooting the Ruby LSP is still not initializing properly, please report an issue